nixos/modules/services/misc/sourcehut/sourcehut.xml

   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    <literal><link linkend="opt-services.sourcehut.enable">services.sourcehut</link></literal>
  18    by default will use
  19    <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>,
  20    <literal><link linkend="opt-services.nginx.enable">services.redis</link></literal>,
  21    <literal><link linkend="opt-services.nginx.enable">services.cron</link></literal>,
  22    and
  23    <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>.
  24   </para>
  25
  26   <para>
  27    A very basic configuration may look like this:
  28 <programlisting>
  29 { pkgs, ... }:
  30 let
  31   fqdn =
  32     let
  33       join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
  34     in join config.networking.hostName config.networking.domain;
  35 in {
  36
  37   networking = {
  38     <link linkend="opt-networking.hostName">hostName</link> = "srht";
  39     <link linkend="opt-networking.domain">domain</link> = "tld";
  40     <link linkend="opt-networking.firewall.allowedTCPPorts">firewall.allowedTCPPorts</link> = [ 22 80 443 ];
  41   };
  42
  43   services.sourcehut = {
  44     <link linkend="opt-services.sourcehut.enable">enable</link> = true;
  45     <link linkend="opt-services.sourcehut.originBase">originBase</link> = fqdn;
  46     <link linkend="opt-services.sourcehut.services">services</link> = [ "meta" "man" "git" ];
  47     <link linkend="opt-services.sourcehut.settings">settings</link> = {
  48         "sr.ht" = {
  49           environment = "production";
  50           global-domain = fqdn;
  51           origin = "https://${fqdn}";
  52           # Produce keys with srht-keygen from <package>sourcehut.coresrht</package>.
  53           network-key = "SECRET";
  54           service-key = "SECRET";
  55         };
  56         webhooks.private-key= "SECRET";
  57     };
  58   };
  59
  60   <link linkend="opt-security.acme.certs._name_.extraDomainNames">security.acme.certs."${fqdn}".extraDomainNames</link> = [
  61     "meta.${fqdn}"
  62     "man.${fqdn}"
  63     "git.${fqdn}"
  64   ];
  65
  66   services.nginx = {
  67     <link linkend="opt-services.nginx.enable">enable</link> = true;
  68     # only recommendedProxySettings are strictly required, but the rest make sense as well.
  69     <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
  70     <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
  71     <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
  72     <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
  73
  74     # Settings to setup what certificates are used for which endpoint.
  75     <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
  76       <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">"${fqdn}".enableACME</link> = true;
  77       <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">"meta.${fqdn}".useACMEHost</link> = fqdn:
  78       <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">"man.${fqdn}".useACMEHost</link> = fqdn:
  79       <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">"git.${fqdn}".useACMEHost</link> = fqdn:
  80     };
  81   };
  82 }
  83 </programlisting>
  84   </para>
  85
  86   <para>
  87    The <literal>hostName</literal> option is used internally to configure the nginx
  88    reverse-proxy. The <literal>settings</literal> attribute set is
  89    used by the configuration generator and the result is placed in <literal>/etc/sr.ht/config.ini</literal>.
  90   </para>
  91  </section>
  92
  93  <section xml:id="module-services-sourcehut-configuration">
  94   <title>Configuration</title>
  95
  96   <para>
  97    All configuration parameters are also stored in
  98    <literal>/etc/sr.ht/config.ini</literal> which is generated by
  99    the module and linked from the store to ensure that all values from <literal>config.ini</literal>
 100    can be modified by the module.
 101   </para>
 102
 103  </section>
 104
 105  <section xml:id="module-services-sourcehut-httpd">
 106   <title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
 107   <para>
 108    By default, <package>nginx</package> is used as reverse-proxy for <package>sourcehut</package>.
 109    However, it's possible to use e.g. <package>httpd</package> by explicitly disabling
 110    <package>nginx</package> using <xref linkend="opt-services.nginx.enable" /> and fixing the
 111    <literal>settings</literal>.
 112   </para>
 113 </section>
 114
 115 </chapter>