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 +++++++++++++++++++++++++++++++++++++
3 files changed, 75 insertions(+)
create mode 100644 doc/snippets/acme-staging-url.scm
create mode 100644 doc/snippets/how-to-set-up-cgit.scm
(limited to 'doc')
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)))
--
cgit v1.2.3