Caddy: Difference between revisions

(6 intermediate revisions by 3 users not shown)

Line 2:

It can also be a reverse proxy to serve multiple web services under one server. Its main features are its simple config setup and automatic HTTPS: It will automatically request and renew a LetsEncrypt certificate so that users of your service get a Browser-trusted and secure connection.

== ~~Get started~~ ==

== Setup ==

To try out Caddy add the following minimal example to your [[NixOS modules | NixOS module]]:

Line 100:

'';

};

</syntaxhighlight>

</syntaxhighlight>In case you would like to forward the real client IP of the request to the backend, add following headers<syntaxhighlight lang="nix">

services.caddy = {

* [https://caddyserver.com/docs/quick-starts/reverse-proxy ~~Caddy reverse proxy~~ documentation]

virtualHosts."example.org".extraConfig = ''

reverse_proxy http://10.25.40.6 {

header_down X-Real-IP {http.request.remote}

header_down X-Forwarded-For {http.request.remote}

}

'';

};

</syntaxhighlight>Fur further reverse proxy configuration, see [https://caddyserver.com/docs/quick-starts/reverse-proxy upstream documentation].

=== Redirect ===

~~Redirecting~~ <code>example.org</code> and <code>old.example.org</code> to <code>www.example.org</code>

Permanent redirect of <code>example.org</code> and <code>old.example.org</code> to <code>www.example.org</code>

Line 113:

Line 120:

virtualHosts."example.org" = {

extraConfig = ''

redir https://www.example.org{uri}

redir https://www.example.org{uri} permanent

'';

~~serverAlias~~ = [ "old.example.org" ];

serverAliases = [ "old.example.org" ];

};

</syntaxhighlight>

Line 137:

Line 144:

You'll need a [[Phpfpm|PHP-FPM]] socket listening on Unix socket path <code>/var/run/phpfpm/localhost.sock</code>.

=== Passing environment variable secrets/configuring acme_dns ===

To prevent any secrets from being put in the nix store (any NixOS setting that writes a config in the Nix store will expose any secret in it), you can use the following setting<syntaxhighlight lang="nixos">

services.caddy = {

enable = true;

globalConfig = ''

acme_dns PROVIDER {

api_key {$APIKEY}

api_secret_key {$APISECRETKEY}

}

'';

};

systemd.services.caddy.serviceConfig.EnvironmentFile = ["/path/to/envfile"];

</syntaxhighlight>And then at '''/path/to/envfile''':<syntaxhighlight>

APIKEY=YOURKEY

APISECRETKEY=OTHERKEY

</syntaxhighlight>

=== Adding plug-ins ===

There are many Issues/PR's about allowing Caddy to be built with plug-ins. Until then, you can use this workaround:<syntaxhighlight lang="nixos">

services.caddy = {

enable = true;

package = (pkgs.callPackage "${builtins.fetchurl https://raw.githubusercontent.com/jpds/nixpkgs/a33b02fa9d664f31dadc8a874eb1a5dbaa9f4ecf/pkgs/servers/caddy/default.nix}" {

externalPlugins = [

{ name = "caddy-dns/porkbun"; repo = "github.com/caddy-dns/porkbun"; version = "4267f6797bf6543d7b20cdc8578a31764face4cf"; }

# Set version to target repository commit hash

];

vendorHash = ""; # Add this as explained in https://github.com/NixOS/nixpkgs/pull/259275#issuecomment-1763478985

});

globalConfig = ''

...

'';

}

</syntaxhighlight>

== Debugging ==

Line 198:

Line 239:

* [https://caddyserver.com/docs/caddyfile/directives/tls Caddy TLS settings documentation]

== Adding Plugins ==

Caddy supports being extended with plugins, which must be added during the build process<ref>https://github.com/caddyserver/caddy?tab=readme-ov-file#with-version-information-andor-plugins</ref>. The simplest option to do this in Nix is by using an override to build a customized version of Caddy.

Follow the instructions for [https://github.com/caddyserver/caddy?tab=readme-ov-file#with-version-information-andor-plugins setting up Caddy to build with plugins], either by using xcaddy, or following the manual steps. In your configuration, override Caddy to build using this local Go module. If you created the main.go file in the same location as your caddy Nix config, it can look something like this:

services.caddy.package = pkgs.caddy.overrideAttrs (

self: super: {

src = ./.;

vendorHash = "";

subPackages = [ ];

}

);

</syntaxhighlight>

== See also ==

@@ Line 2: / Line 2: @@
 It can also be a reverse proxy to serve multiple web services under one server. Its main features are its simple config setup and automatic HTTPS: It will automatically request and renew a LetsEncrypt certificate so that users of your service get a Browser-trusted and secure connection.
-== Get started ==
+== Setup ==
 To try out Caddy add the following minimal example to your [[NixOS modules | NixOS module]]:
@@ Line 100: / Line 100: @@
    '';
 };
-</syntaxhighlight>
+</syntaxhighlight>In case you would like to forward the real client IP of the request to the backend, add following headers<syntaxhighlight lang="nix">
+services.caddy = {
-* [https://caddyserver.com/docs/quick-starts/reverse-proxy Caddy reverse proxy documentation]
+  virtualHosts."example.org".extraConfig = ''
+    reverse_proxy http://10.25.40.6 {
+      header_down X-Real-IP {http.request.remote}
+      header_down X-Forwarded-For {http.request.remote}
+    }
+  '';
+};
+</syntaxhighlight>Fur further reverse proxy configuration, see [https://caddyserver.com/docs/quick-starts/reverse-proxy upstream documentation].
 === Redirect ===
-Redirecting <code>example.org</code> and <code>old.example.org</code> to <code>www.example.org</code>
+Permanent redirect of <code>example.org</code> and <code>old.example.org</code> to <code>www.example.org</code>
 <syntaxhighlight lang="nix">
@@ Line 113: / Line 120: @@
    virtualHosts."example.org" = {
      extraConfig = ''
-       redir https://www.example.org{uri}
+       redir https://www.example.org{uri} permanent
     '';
-     serverAlias = [ "old.example.org" ];
+     serverAliases = [ "old.example.org" ];
 };
 </syntaxhighlight>
@@ Line 137: / Line 144: @@
 You'll need a [[Phpfpm|PHP-FPM]] socket listening on Unix socket path <code>/var/run/phpfpm/localhost.sock</code>.
+=== Passing environment variable secrets/configuring acme_dns ===
+To prevent any secrets from being put in the nix store (any NixOS setting that writes a config in the Nix store will expose any secret in it), you can use the following setting<syntaxhighlight lang="nixos">
+services.caddy = {
+  enable = true;
+  globalConfig = ''
+    acme_dns PROVIDER {
+      api_key {$APIKEY}
+      api_secret_key {$APISECRETKEY}
+    }
+  '';
+};
+systemd.services.caddy.serviceConfig.EnvironmentFile = ["/path/to/envfile"];
+</syntaxhighlight>And then at '''/path/to/envfile''':<syntaxhighlight>
+APIKEY=YOURKEY
+APISECRETKEY=OTHERKEY
+</syntaxhighlight>
+=== Adding plug-ins ===
+There are many Issues/PR's about allowing Caddy to be built with plug-ins. Until then, you can use this workaround:<syntaxhighlight lang="nixos">
+services.caddy = {
+  enable = true;
+  package = (pkgs.callPackage "${builtins.fetchurl https://raw.githubusercontent.com/jpds/nixpkgs/a33b02fa9d664f31dadc8a874eb1a5dbaa9f4ecf/pkgs/servers/caddy/default.nix}" {
+    externalPlugins = [
+      { name = "caddy-dns/porkbun"; repo = "github.com/caddy-dns/porkbun"; version = "4267f6797bf6543d7b20cdc8578a31764face4cf"; }
+      # Set version to target repository commit hash
+    ];
+    vendorHash = "";  # Add this as explained in https://github.com/NixOS/nixpkgs/pull/259275#issuecomment-1763478985
+  });
+  globalConfig = ''
+    ...
+  '';
+}
+</syntaxhighlight>
 == Debugging ==
@@ Line 198: / Line 239: @@
 * [https://caddyserver.com/docs/caddyfile/directives/tls Caddy TLS settings documentation]
+== Adding Plugins ==
+Caddy supports being extended with plugins, which must be added during the build process<ref>https://github.com/caddyserver/caddy?tab=readme-ov-file#with-version-information-andor-plugins</ref>. The simplest option to do this in Nix is by using an override to build a customized version of Caddy.
+Follow the instructions for [https://github.com/caddyserver/caddy?tab=readme-ov-file#with-version-information-andor-plugins setting up Caddy to build with plugins], either by using xcaddy, or following the manual steps. In your configuration, override Caddy to build using this local Go module. If you created the main.go file in the same location as your caddy Nix config, it can look something like this:
+<syntaxhighlight lang="nix">
+services.caddy.package = pkgs.caddy.overrideAttrs (
+  self: super: {
+    src = ./.;
+    vendorHash = "";
+    subPackages = [ ];
+  }
+);
+</syntaxhighlight>
 == See also ==