diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/forge.skb | 33 | ||||
| -rw-r--r-- | doc/snippets/acme-staging-url.scm | 4 | ||||
| -rw-r--r-- | doc/snippets/how-to-set-up-cgit.scm | 38 |
3 files changed, 75 insertions, 0 deletions
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))) |