From e9615a02c6713e287e0a04c79bdd0ac365304cb0 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Mon, 7 Aug 2023 16:44:40 +0100
Subject: nginx: Add forge-nginx service.

* guix/forge/nginx.scm, doc/snippets/acme-restart-nginx-sudoers.scm:
New files.
* doc/forge.skb (Services)[forge nginx service]: Document the
forge-nginx service.
---
 doc/forge.skb                               | 43 +++++++++++++++++++++++++++++
 doc/snippets/acme-restart-nginx-sudoers.scm |  7 +++++
 2 files changed, 50 insertions(+)
 create mode 100644 doc/snippets/acme-restart-nginx-sudoers.scm

(limited to 'doc')

diff --git a/doc/forge.skb b/doc/forge.skb
index c1c43c7..f230d2c 100644
--- a/doc/forge.skb
+++ b/doc/forge.skb
@@ -189,6 +189,49 @@ repeated below for your reference.])
                   :file "doc/snippets/tutorial.scm")))
   (chapter :title [Services]
            :ident "chapter-services"
+    (section :title [forge nginx service]
+             :ident "section-forge-nginx-service"
+      (p [The forge nginx service is a wrapper around the nginx web
+service in Guix upstream. It features]
+         (itemize
+          (item [automatic HTTPS for all sites through the ,(ref :ident
+"section-acme-service" :text "ACME service")])
+          (item [HTTP endpoint that redirects to HTTPS and responds to
+ACME HTTP-01 challenges])
+          (item [automatic provision of ,(ref :url
+"https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security" :text
+(abbr :short "HSTS" :long "HTTP Strict Transport Security"))
+headers])))
+      (p [When using this service, you must allow the ,(samp [acme])
+user to restart nginx using ,(command [sudo]). This is so that newly
+obtained certificates can be deployed to nginx. You may achieve this
+with the following in the ,(code [sudoers-file]) field of your ,(code
+[operating-system]) definition.]
+         (prog (source :language scheme
+                       :file "doc/snippets/acme-restart-nginx-sudoers.scm")
+               :line #f))
+      (description
+       (record-documentation "guix/forge/nginx.scm" '<forge-nginx-configuration>
+         (record-field "http-listen"
+           [Socket to listen on for HTTP requests. Socket may be a
+,(record-ref "<forge-host-socket>"), ,(record-ref
+"<forge-ip-socket>"), or ,(record-ref "<forge-unix-socket>") object.])
+         (record-field "https-listen"
+           [Socket to listen on for HTTPS requests. Socket may be a
+,(record-ref "<forge-host-socket>"), ,(record-ref
+"<forge-ip-socket>"), or ,(record-ref "<forge-unix-socket>") object.])
+         (record-field "acme-state-directory"
+           [State directory of the ,(ref :ident "section-acme-service"
+:text "ACME service")])
+         (record-field "acme-challenge-directory"
+           [Directory to serve on ,(samp
+[/.well-known/acme-challenge/]) in response to ACME HTTP-01
+challenges])
+         (record-field "server-blocks"
+           [List of ,(ref :url
+"https://guix.gnu.org/manual/en/html_node/Web-Services.html#index-nginx_002dserver_002dconfiguration"
+:text "<nginx-server-configuration>") objects describing server blocks
+to add to the nginx configuration]))))
     (section :title [ACME service]
              :ident "section-acme-service"
       (p [,(abbr :short "ACME" :long "Automatic Certificate Management
diff --git a/doc/snippets/acme-restart-nginx-sudoers.scm b/doc/snippets/acme-restart-nginx-sudoers.scm
new file mode 100644
index 0000000..7f705b9
--- /dev/null
+++ b/doc/snippets/acme-restart-nginx-sudoers.scm
@@ -0,0 +1,7 @@
+(operating-system
+  …
+  (sudoers-file
+   (mixed-text-file "sudoers"
+     "@include " %sudoers-specification
+     "\nacme ALL = NOPASSWD: " (file-append shepherd "/bin/herd") " restart nginx\n"))
+  …)
-- 
cgit v1.2.3