The nixos/caddy module is somewhat old by now
and has undergone quite some refactors.
This specific module option (originally named
`ca`) used to make a bit more sense when
Caddy did not have multiple ACME CAs as
fallback (LE & ZeroSSL) by configured by
default yet (ZeroSSL came with v2.3.0).
I also rephrased the description slightly,
to mention Caddy's automatic issuer fallback
and a note which this option maps to in the
Caddyfile, to provide a bit more context and
a more up-to-date recommendation.
Specifically that "fine-grained configuration"
section comes from a time when this module did
some custom tls/issuer config json merging
with the templated Caddyfile using `jq`.
The "The URL to the ACME CA's directory"
section is a word-for-word copy from the
official Caddy docs, which also include a link
to LE's docs to the referenced staging
endpoint. So I added that as well.
The nixos module uses `caddy fmt` to *format* the generated Caddyfile.
v2.6.3 slightly altered `caddy fmt`'s behavior.
Excerpt from https://github.com/caddyserver/caddy/releases/tag/v2.6.3
> cmd: caddy fmt return code is 1 if not formatted
> cmd: fmt exit successfully after overwriting config file
Which is why the internal `Caddyfile-formatted` now uses `cp` and `caddy fmt --overwrite` instead
conversions were done using https://github.com/pennae/nix-doc-munge
using (probably) rev f34e145 running
nix-doc-munge nixos/**/*.nix
nix-doc-munge --import nixos/**/*.nix
the tool ensures that only changes that could affect the generated
manual *but don't* are committed, other changes require manual review
and are discarded.
This patch follows an upstream commit[1].
Before this patch, if acme module is used, caddy will still use an old
cert even a new one is available. The cause is that without --force
flag, caddy will not reload an unchanged config.
Refer to that commit[1] message for more information.
[1]: 979e498d6d
Before this patch, the caddy process has acme in its supplementary
group because of the SupplementaryGroups in its service config, which
may give it more permission than needed, is inconsistent with the
documentation of services.caddy.virtualHosts.<name>.useACMEHost and is
redundant since we have mkCertOwnershipAssertion in assertions.
This patch fixes these problems by defaulting the group of needed
certs to caddy, which is what other web servers like nginx do and
deleting SupplementaryGroups config.
