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 ++++++++++++++++++++++++++++++++
 doc/snippets/acme-staging-url.scm   |  4 ++++
 doc/snippets/how-to-set-up-cgit.scm | 38 +++++++++++++++++++++++++++++++++++++
 tissue.scm                          |  1 +
 4 files changed, 76 insertions(+)
 create mode 100644 doc/snippets/acme-staging-url.scm
 create mode 100644 doc/snippets/how-to-set-up-cgit.scm

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]
diff --git a/doc/snippets/acme-staging-url.scm b/doc/snippets/acme-staging-url.scm
new file mode 100644
index 0000000..daa1052
--- /dev/null
+++ b/doc/snippets/acme-staging-url.scm
@@ -0,0 +1,4 @@
+(service acme-service-type
+         (acme-configuration
+          (email "foo@example.org")
+          (acme-url %letsencrypt-staging-url)))
diff --git a/doc/snippets/how-to-set-up-cgit.scm b/doc/snippets/how-to-set-up-cgit.scm
new file mode 100644
index 0000000..8bb1975
--- /dev/null
+++ b/doc/snippets/how-to-set-up-cgit.scm
@@ -0,0 +1,38 @@
+(use-modules (gnu)
+             ((gnu packages admin) #:select (shepherd))
+             (forge acme)
+             (forge cgit)
+             (forge nginx)
+             (forge socket))
+
+(operating-system
+  (host-name "forge")
+  (timezone "UTC")
+  (locale "en_US.utf8")
+  (bootloader (bootloader-configuration
+               (bootloader grub-bootloader)
+               (targets (list "/dev/sdX"))))
+  (file-systems %base-file-systems)
+  (sudoers-file
+   (mixed-text-file "sudoers"
+                    "@include " %sudoers-specification
+                    ;; Permit the acme user to restart nginx.
+                    "\nacme ALL = NOPASSWD: "
+                    (file-append shepherd "/bin/herd")
+                    " restart nginx\n"))
+  (services (cons* (service cgit-service-type
+                            (cgit-configuration
+                             (server-name "git.example.org")
+                             (repository-directory "/srv/git")))
+                   (service forge-nginx-service-type
+                            (forge-nginx-configuration
+                             (http-listen (forge-ip-socket
+                                           (ip "0.0.0.0")
+                                           (port 8080)))
+                             (https-listen (forge-ip-socket
+                                            (ip "0.0.0.0")
+                                            (port 4443)))))
+                   (service acme-service-type
+                            (acme-configuration
+                             (email "foo@example.org")))
+                   %base-services)))
diff --git a/tissue.scm b/tissue.scm
index 890dd88..3717bea 100644
--- a/tissue.scm
+++ b/tissue.scm
@@ -36,6 +36,7 @@
                                                              identifier)))
                                   (list "chapter-introduction"
                                         "chapter-tutorial"
+                                        "chapter-how-to"
                                         "chapter-services"
                                         "chapter-reference"))
                              (map (lambda (commit)
-- 
cgit v1.2.3