aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/forge.skb43
-rw-r--r--doc/snippets/acme-restart-nginx-sudoers.scm7
2 files changed, 50 insertions, 0 deletions
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"))
+ …)