nixos docs: update for Nginx + ACME (#21320)

Closes #20698.

1 files changed, 20 insertions, 42 deletions

diff --git a/nixos/modules/security/acme.xml b/nixos/modules/security/acme.xml
index 6fddb27e6a34..823806f4641b 100644
--- a/nixos/modules/security/acme.xml
+++ b/nixos/modules/security/acme.xml
@@ -67,52 +67,30 @@ options for the <literal>security.acme</literal> module.</para>
 </section>
 
 <section><title>Using ACME certificates in Nginx</title>
-<para>In practice ACME is mostly used for retrieval and renewal of
-  certificates that will be used in a webserver like Nginx. A configuration for
-  Nginx that uses the certificates from ACME for
-  <literal>foo.example.com</literal> will look similar to:
+<para>NixOS supports fetching ACME certificates for you by setting
+<literal>enableACME = true;</literal> in a virtualHost config. We
+first create self-signed placeholder certificates in place of the
+real ACME certs. The placeholder certs are overwritten when the ACME
+certs arrive. For <literal>foo.example.com</literal> the config would
+look like.
 </para>
 
 <programlisting>
-security.acme.certs."foo.example.com" = {
-  webroot = config.security.acme.directory + "/acme-challenge";
-  email = "foo@example.com";
-  user = "nginx";
-  group = "nginx";
-  postRun = "systemctl restart nginx.service";
-};
-services.nginx.httpConfig = ''
-  server {
-    server_name foo.example.com;
-    listen 80;
-    listen [::]:80;
-
-    location /.well-known/acme-challenge {
-      root /var/www/challenges;
-    }
-
-    location / {
-      return 301 https://$host$request_uri;
-    }
-  }
-
-  server {
-    server_name foo.example.com;
-    listen 443 ssl;
-    ssl_certificate     ${config.security.acme.directory}/foo.example.com/fullchain.pem;
-    ssl_certificate_key ${config.security.acme.directory}/foo.example.com/key.pem;
-    root /var/www/foo.example.com/;
-  }
-'';
+services.nginx = {
+  enable = true;
+  virtualHosts = {
+    "foo.example.com" = {
+      forceSSL = true;
+      enableACME = true;
+      locations."/" = {
+        root = "/var/www";
+      };
+    };
+  };
+}
 </programlisting>
 
-<para>Now Nginx will try to use the certificates that will be retrieved by ACME.
-  ACME needs Nginx (or any other webserver) to function and Nginx needs
-  the certificates to actually start. For this reason the ACME module
-  automatically generates self-signed certificates that will be used by Nginx to
-  start. After that Nginx is used by ACME to retrieve the actual ACME
-  certificates. <literal>security.acme.preliminarySelfsigned</literal> can be
-  used to control whether to generate the self-signed certificates.
-</para>
+<para>At the moment you still have to restart Nginx after the ACME
+certs arrive.</para>
 </section>
 </chapter>