nixos/caddy: change `acmeCA` default to `null`

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.

1 files changed, 13 insertions, 5 deletions

diff --git a/nixos/modules/services/web-servers/caddy/default.nix b/nixos/modules/services/web-servers/caddy/default.nix
index f5a9cfac5d77..b253a04150d7 100644
--- a/nixos/modules/services/web-servers/caddy/default.nix
+++ b/nixos/modules/services/web-servers/caddy/default.nix
@@ -245,15 +245,23 @@ in
     };
 
     acmeCA = mkOption {
-      default = "https://acme-v02.api.letsencrypt.org/directory";
-      example = "https://acme-staging-v02.api.letsencrypt.org/directory";
+      default = null;
+      example = "https://acme-v02.api.letsencrypt.org/directory";
       type = with types; nullOr str;
       description = lib.mdDoc ''
+        ::: {.note}
+        Sets the [`acme_ca` option](https://caddyserver.com/docs/caddyfile/options#acme-ca)
+        in the global options block of the resulting Caddyfile.
+        :::
+
         The URL to the ACME CA's directory. It is strongly recommended to set
-        this to Let's Encrypt's staging endpoint for testing or development.
+        this to `https://acme-staging-v02.api.letsencrypt.org/directory` for
+        Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/)
+        while testing or in development.
 
-        Set it to `null` if you want to write a more
-        fine-grained configuration manually.
+        Value `null` should be prefered for production setups,
+        as it omits the `acme_ca` option to enable
+        [automatic issuer fallback](https://caddyserver.com/docs/automatic-https#issuer-fallback).
       '';
     };