From 7c8bc2c9eb661ee0468dd195ab6e8b7258662bc6 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Mon, 14 Aug 2023 22:28:04 +0100
Subject: doc: Add cgit setup how to.

* doc/forge.skb (How To): New chapter.
* doc/snippets/acme-staging-url.scm,
doc/snippets/how-to-set-up-cgit.scm: New files.
* tissue.scm (#:indexed-documents): Index chapter-how-to.
---
 doc/forge.skb | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

(limited to 'doc/forge.skb')

diff --git a/doc/forge.skb b/doc/forge.skb
index 8d59bef..e772b34 100644
--- a/doc/forge.skb
+++ b/doc/forge.skb
@@ -187,6 +187,39 @@ per your needs. The overall configuration used in this tutorial is
 repeated below for your reference.])
     (prog (source :language scheme
                   :file "doc/snippets/tutorial.scm")))
+  (chapter :title [How To]
+           :ident "chapter-how-to"
+    (section :title [How to set up cgit]
+             :ident "section-how-to-set-up-cgit"
+      (p [guix-forge comes with an end-to-end cgit solution that not
+only sets up cgit itself but also an nginx server complete with
+automatically renewed TLS certificates.])
+      (p [The cgit service uses the forge-nginx service as its web
+server. The forge-nginx service in turn uses the ACME service to fetch
+and renew TLS certificates. Here's a minimal working configuration.])
+      (prog (source :language scheme
+                    :file "doc/snippets/how-to-set-up-cgit.scm")
+            :line #f)
+      (p [The cgit service configuration specifies the domain ,(samp
+[git.example.org]) to serve cgit on and the ,(file "/srv/git")
+repository directory containing bare git repositories to publish. The
+forge nginx service configuration specifies the ports to serve HTTP
+and HTTPS on. The ACME service configuration specifies the email
+address to register an ACME account with. The sudoers file declaration
+is required to allow the ,(samp [acme]) user to restart the nginx
+server when a certificate is renewed. The configured machine will
+start out with self-signed certificates. Run ,(samp [/usr/bin/acme
+renew]) the first time to get CA-issued certificates. Thereafter,
+certificates will auto-renew via a cron job.])
+      (p [When testing your deployment, it might help to start with
+the Let's Encrypt staging server as shown below. This will give you
+dummy certificates, but will help you avoid running afoul of Let's
+Encrypt rate limits. Once you know everything works, delete the ACME
+state directory (,(file "/var/lib/acme") by default) and run ,(samp
+[/usr/bin/acme renew]) again to get real certificates.]
+         (prog (source :language scheme
+                       :file "doc/snippets/acme-staging-url.scm")
+               :line #f))))
   (chapter :title [Services]
            :ident "chapter-services"
     (section :title [Git web viewers]
-- 
cgit v1.2.3