From 0cc9d6cf5d264b4a561105c667c9d1065d05528f Mon Sep 17 00:00:00 2001 From: pennae Date: Tue, 3 Jan 2023 05:10:27 +0100 Subject: nixos/sourcehut: convert manual chapter to MD --- nixos/modules/services/misc/sourcehut/default.nix | 2 + nixos/modules/services/misc/sourcehut/sourcehut.md | 93 ++++++++++++++ .../modules/services/misc/sourcehut/sourcehut.xml | 138 ++++++++++----------- 3 files changed, 160 insertions(+), 73 deletions(-) create mode 100644 nixos/modules/services/misc/sourcehut/sourcehut.md diff --git a/nixos/modules/services/misc/sourcehut/default.nix b/nixos/modules/services/misc/sourcehut/default.nix index 7dd254e3492..da3bf069813 100644 --- a/nixos/modules/services/misc/sourcehut/default.nix +++ b/nixos/modules/services/misc/sourcehut/default.nix @@ -1390,6 +1390,8 @@ in '') ]; + # Don't edit the docbook xml directly, edit the md and generate it: + # `pandoc sourcehut.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > sourcehut.xml` meta.doc = ./sourcehut.xml; meta.maintainers = with maintainers; [ tomberek ]; } diff --git a/nixos/modules/services/misc/sourcehut/sourcehut.md b/nixos/modules/services/misc/sourcehut/sourcehut.md new file mode 100644 index 00000000000..44d58aa0bef --- /dev/null +++ b/nixos/modules/services/misc/sourcehut/sourcehut.md @@ -0,0 +1,93 @@ +# Sourcehut {#module-services-sourcehut} + +[Sourcehut](https://sr.ht.com/) is an open-source, +self-hostable software development platform. The server setup can be automated using +[services.sourcehut](#opt-services.sourcehut.enable). + +## Basic usage {#module-services-sourcehut-basic-usage} + +Sourcehut is a Python and Go based set of applications. +This NixOS module also provides basic configuration integrating Sourcehut into locally running +`services.nginx`, `services.redis.servers.sourcehut`, `services.postfix` +and `services.postgresql` services. + +A very basic configuration may look like this: +``` +{ pkgs, ... }: +let + fqdn = + let + join = hostName: domain: hostName + optionalString (domain != null) ".${domain}"; + in join config.networking.hostName config.networking.domain; +in { + + networking = { + hostName = "srht"; + domain = "tld"; + firewall.allowedTCPPorts = [ 22 80 443 ]; + }; + + services.sourcehut = { + enable = true; + git.enable = true; + man.enable = true; + meta.enable = true; + nginx.enable = true; + postfix.enable = true; + postgresql.enable = true; + redis.enable = true; + settings = { + "sr.ht" = { + environment = "production"; + global-domain = fqdn; + origin = "https://${fqdn}"; + # Produce keys with srht-keygen from sourcehut.coresrht. + network-key = "/run/keys/path/to/network-key"; + service-key = "/run/keys/path/to/service-key"; + }; + webhooks.private-key= "/run/keys/path/to/webhook-key"; + }; + }; + + security.acme.certs."${fqdn}".extraDomainNames = [ + "meta.${fqdn}" + "man.${fqdn}" + "git.${fqdn}" + ]; + + services.nginx = { + enable = true; + # only recommendedProxySettings are strictly required, but the rest make sense as well. + recommendedTlsSettings = true; + recommendedOptimisation = true; + recommendedGzipSettings = true; + recommendedProxySettings = true; + + # Settings to setup what certificates are used for which endpoint. + virtualHosts = { + "${fqdn}".enableACME = true; + "meta.${fqdn}".useACMEHost = fqdn: + "man.${fqdn}".useACMEHost = fqdn: + "git.${fqdn}".useACMEHost = fqdn: + }; + }; +} +``` + + The `hostName` option is used internally to configure the nginx +reverse-proxy. The `settings` attribute set is +used by the configuration generator and the result is placed in `/etc/sr.ht/config.ini`. + +## Configuration {#module-services-sourcehut-configuration} + +All configuration parameters are also stored in +`/etc/sr.ht/config.ini` which is generated by +the module and linked from the store to ensure that all values from `config.ini` +can be modified by the module. + +## Using an alternative webserver as reverse-proxy (e.g. `httpd`) {#module-services-sourcehut-httpd} + +By default, `nginx` is used as reverse-proxy for `sourcehut`. +However, it's possible to use e.g. `httpd` by explicitly disabling +`nginx` using [](#opt-services.nginx.enable) and fixing the +`settings`. diff --git a/nixos/modules/services/misc/sourcehut/sourcehut.xml b/nixos/modules/services/misc/sourcehut/sourcehut.xml index 5f9cc75bc9f..883b6f01ef8 100644 --- a/nixos/modules/services/misc/sourcehut/sourcehut.xml +++ b/nixos/modules/services/misc/sourcehut/sourcehut.xml @@ -1,41 +1,36 @@ - - Sourcehut - - Sourcehut is an open-source, - self-hostable software development platform. The server setup can be automated using - services.sourcehut. - - -
- Basic usage + + Sourcehut - Sourcehut is a Python and Go based set of applications. - This NixOS module also provides basic configuration integrating Sourcehut into locally running - services.nginx, - services.redis.servers.sourcehut, - services.postfix - and - services.postgresql services. + Sourcehut is an + open-source, self-hostable software development platform. The server + setup can be automated using + services.sourcehut. - - - A very basic configuration may look like this: - +
+ Basic usage + + Sourcehut is a Python and Go based set of applications. This NixOS + module also provides basic configuration integrating Sourcehut + into locally running services.nginx, + services.redis.servers.sourcehut, + services.postfix and + services.postgresql services. + + + A very basic configuration may look like this: + + { pkgs, ... }: let fqdn = let - join = hostName: domain: hostName + optionalString (domain != null) ".${domain}"; + join = hostName: domain: hostName + optionalString (domain != null) ".${domain}"; in join config.networking.hostName config.networking.domain; in { networking = { - hostName = "srht"; - domain = "tld"; + hostName = "srht"; + domain = "tld"; firewall.allowedTCPPorts = [ 22 80 443 ]; }; @@ -49,22 +44,22 @@ in { postgresql.enable = true; redis.enable = true; settings = { - "sr.ht" = { - environment = "production"; + "sr.ht" = { + environment = "production"; global-domain = fqdn; - origin = "https://${fqdn}"; + origin = "https://${fqdn}"; # Produce keys with srht-keygen from sourcehut.coresrht. - network-key = "/run/keys/path/to/network-key"; - service-key = "/run/keys/path/to/service-key"; + network-key = "/run/keys/path/to/network-key"; + service-key = "/run/keys/path/to/service-key"; }; - webhooks.private-key= "/run/keys/path/to/webhook-key"; + webhooks.private-key= "/run/keys/path/to/webhook-key"; }; }; - security.acme.certs."${fqdn}".extraDomainNames = [ - "meta.${fqdn}" - "man.${fqdn}" - "git.${fqdn}" + security.acme.certs."${fqdn}".extraDomainNames = [ + "meta.${fqdn}" + "man.${fqdn}" + "git.${fqdn}" ]; services.nginx = { @@ -77,43 +72,40 @@ in { # Settings to setup what certificates are used for which endpoint. virtualHosts = { - "${fqdn}".enableACME = true; - "meta.${fqdn}".useACMEHost = fqdn: - "man.${fqdn}".useACMEHost = fqdn: - "git.${fqdn}".useACMEHost = fqdn: + "${fqdn}".enableACME = true; + "meta.${fqdn}".useACMEHost = fqdn: + "man.${fqdn}".useACMEHost = fqdn: + "git.${fqdn}".useACMEHost = fqdn: }; }; } - - - - The hostName option is used internally to configure the nginx - reverse-proxy. The settings attribute set is - used by the configuration generator and the result is placed in /etc/sr.ht/config.ini. - -
- -
- Configuration - - - All configuration parameters are also stored in - /etc/sr.ht/config.ini which is generated by - the module and linked from the store to ensure that all values from config.ini - can be modified by the module. - - -
- -
- Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>) - - By default, nginx is used as reverse-proxy for sourcehut. - However, it's possible to use e.g. httpd by explicitly disabling - nginx using and fixing the - settings. - -
- + + The hostName option is used internally to + configure the nginx reverse-proxy. The settings + attribute set is used by the configuration generator and the + result is placed in /etc/sr.ht/config.ini. + +
+
+ Configuration + + All configuration parameters are also stored in + /etc/sr.ht/config.ini which is generated by the + module and linked from the store to ensure that all values from + config.ini can be modified by the module. + +
+
+ Using an alternative webserver as reverse-proxy (e.g. + <literal>httpd</literal>) + + By default, nginx is used as reverse-proxy for + sourcehut. However, it's possible to use e.g. + httpd by explicitly disabling + nginx using + and fixing the + settings. + +
-- cgit 1.4.1