pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-services-sourcehut">
6 <title>Sourcehut</title>
7 <para>
8 <link xlink:href="https://sr.ht.com/">Sourcehut</link> is an open-source,
9 self-hostable software development platform. The server setup can be automated using
10 <link linkend="opt-services.sourcehut.enable">services.sourcehut</link>.
11 </para>
12
13 <section xml:id="module-services-sourcehut-basic-usage">
14 <title>Basic usage</title>
15 <para>
16 Sourcehut is a Python and Go based set of applications.
17 This NixOS module also provides basic configuration integrating Sourcehut into locally running
18 <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>,
19 <literal><link linkend="opt-services.redis.servers">services.redis.servers.sourcehut</link></literal>,
20 <literal><link linkend="opt-services.postfix.enable">services.postfix</link></literal>
21 and
22 <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal> services.
23 </para>
24
25 <para>
26 A very basic configuration may look like this:
27<programlisting>
28{ pkgs, ... }:
29let
30 fqdn =
31 let
32 join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
33 in join config.networking.hostName config.networking.domain;
34in {
35
36 networking = {
37 <link linkend="opt-networking.hostName">hostName</link> = "srht";
38 <link linkend="opt-networking.domain">domain</link> = "tld";
39 <link linkend="opt-networking.firewall.allowedTCPPorts">firewall.allowedTCPPorts</link> = [ 22 80 443 ];
40 };
41
42 services.sourcehut = {
43 <link linkend="opt-services.sourcehut.enable">enable</link> = true;
44 <link linkend="opt-services.sourcehut.git.enable">git.enable</link> = true;
45 <link linkend="opt-services.sourcehut.man.enable">man.enable</link> = true;
46 <link linkend="opt-services.sourcehut.meta.enable">meta.enable</link> = true;
47 <link linkend="opt-services.sourcehut.nginx.enable">nginx.enable</link> = true;
48 <link linkend="opt-services.sourcehut.postfix.enable">postfix.enable</link> = true;
49 <link linkend="opt-services.sourcehut.postgresql.enable">postgresql.enable</link> = true;
50 <link linkend="opt-services.sourcehut.redis.enable">redis.enable</link> = true;
51 <link linkend="opt-services.sourcehut.settings">settings</link> = {
52 "sr.ht" = {
53 environment = "production";
54 global-domain = fqdn;
55 origin = "https://${fqdn}";
56 # Produce keys with srht-keygen from <package>sourcehut.coresrht</package>.
57 network-key = "/run/keys/path/to/network-key";
58 service-key = "/run/keys/path/to/service-key";
59 };
60 webhooks.private-key= "/run/keys/path/to/webhook-key";
61 };
62 };
63
64 <link linkend="opt-security.acme.certs._name_.extraDomainNames">security.acme.certs."${fqdn}".extraDomainNames</link> = [
65 "meta.${fqdn}"
66 "man.${fqdn}"
67 "git.${fqdn}"
68 ];
69
70 services.nginx = {
71 <link linkend="opt-services.nginx.enable">enable</link> = true;
72 # only recommendedProxySettings are strictly required, but the rest make sense as well.
73 <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
74 <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
75 <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
76 <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
77
78 # Settings to setup what certificates are used for which endpoint.
79 <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
80 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">"${fqdn}".enableACME</link> = true;
81 <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">"meta.${fqdn}".useACMEHost</link> = fqdn:
82 <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">"man.${fqdn}".useACMEHost</link> = fqdn:
83 <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">"git.${fqdn}".useACMEHost</link> = fqdn:
84 };
85 };
86}
87</programlisting>
88 </para>
89
90 <para>
91 The <literal>hostName</literal> option is used internally to configure the nginx
92 reverse-proxy. The <literal>settings</literal> attribute set is
93 used by the configuration generator and the result is placed in <literal>/etc/sr.ht/config.ini</literal>.
94 </para>
95 </section>
96
97 <section xml:id="module-services-sourcehut-configuration">
98 <title>Configuration</title>
99
100 <para>
101 All configuration parameters are also stored in
102 <literal>/etc/sr.ht/config.ini</literal> which is generated by
103 the module and linked from the store to ensure that all values from <literal>config.ini</literal>
104 can be modified by the module.
105 </para>
106
107 </section>
108
109 <section xml:id="module-services-sourcehut-httpd">
110 <title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
111 <para>
112 By default, <package>nginx</package> is used as reverse-proxy for <package>sourcehut</package>.
113 However, it's possible to use e.g. <package>httpd</package> by explicitly disabling
114 <package>nginx</package> using <xref linkend="opt-services.nginx.enable" /> and fixing the
115 <literal>settings</literal>.
116 </para>
117</section>
118
119</chapter>