nixos/modules/services/misc/gitlab.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-gitlab">
   6  <title>GitLab</title>
   7  <para>
   8   GitLab is a feature-rich git hosting service.
   9  </para>
  10  <section xml:id="module-services-gitlab-prerequisites">
  11   <title>Prerequisites</title>
  12
  13   <para>
  14    The <literal>gitlab</literal> service exposes only an Unix socket at
  15    <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to
  16    configure a webserver to proxy HTTP requests to the socket.
  17   </para>
  18
  19   <para>
  20    For instance, the following configuration could be used to use nginx as
  21    frontend proxy:
  22 <programlisting>
  23 <link linkend="opt-services.nginx.enable">services.nginx</link> = {
  24   <link linkend="opt-services.nginx.enable">enable</link> = true;
  25   <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
  26   <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
  27   <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
  28   <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
  29   <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link>."git.example.com" = {
  30     <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
  31     <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
  32     <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/".proxyPass</link> = "http://unix:/run/gitlab/gitlab-workhorse.socket";
  33   };
  34 };
  35 </programlisting>
  36   </para>
  37  </section>
  38  <section xml:id="module-services-gitlab-configuring">
  39   <title>Configuring</title>
  40
  41   <para>
  42    GitLab depends on both PostgreSQL and Redis and will automatically enable
  43    both services. In the case of PostgreSQL, a database and a role will be
  44    created.
  45   </para>
  46
  47   <para>
  48    The default state dir is <literal>/var/gitlab/state</literal>. This is where
  49    all data like the repositories and uploads will be stored.
  50   </para>
  51
  52   <para>
  53    A basic configuration with some custom settings could look like this:
  54 <programlisting>
  55 services.gitlab = {
  56   <link linkend="opt-services.gitlab.enable">enable</link> = true;
  57   <link linkend="opt-services.gitlab.databasePasswordFile">databasePasswordFile</link> = "/var/keys/gitlab/db_password";
  58   <link linkend="opt-services.gitlab.initialRootPasswordFile">initialRootPasswordFile</link> = "/var/keys/gitlab/root_password";
  59   <link linkend="opt-services.gitlab.https">https</link> = true;
  60   <link linkend="opt-services.gitlab.host">host</link> = "git.example.com";
  61   <link linkend="opt-services.gitlab.port">port</link> = 443;
  62   <link linkend="opt-services.gitlab.user">user</link> = "git";
  63   <link linkend="opt-services.gitlab.group">group</link> = "git";
  64   smtp = {
  65     <link linkend="opt-services.gitlab.smtp.enable">enable</link> = true;
  66     <link linkend="opt-services.gitlab.smtp.address">address</link> = "localhost";
  67     <link linkend="opt-services.gitlab.smtp.port">port</link> = 25;
  68   };
  69   secrets = {
  70     <link linkend="opt-services.gitlab.secrets.dbFile">dbFile</link> = "/var/keys/gitlab/db";
  71     <link linkend="opt-services.gitlab.secrets.secretFile">secretFile</link> = "/var/keys/gitlab/secret";
  72     <link linkend="opt-services.gitlab.secrets.otpFile">otpFile</link> = "/var/keys/gitlab/otp";
  73     <link linkend="opt-services.gitlab.secrets.jwsFile">jwsFile</link> = "/var/keys/gitlab/jws";
  74   };
  75   <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> = {
  76     gitlab = {
  77       email_from = "gitlab-no-reply@example.com";
  78       email_display_name = "Example GitLab";
  79       email_reply_to = "gitlab-no-reply@example.com";
  80       default_projects_features = { builds = false; };
  81     };
  82   };
  83 };
  84 </programlisting>
  85   </para>
  86
  87   <para>
  88    If you're setting up a new GitLab instance, generate new
  89    secrets. You for instance use <literal>tr -dc A-Za-z0-9 &lt;
  90    /dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal> to
  91    generate a new db secret. Make sure the files can be read by, and
  92    only by, the user specified by <link
  93    linkend="opt-services.gitlab.user">services.gitlab.user</link>. GitLab
  94    encrypts sensitive data stored in the database. If you're restoring
  95    an existing GitLab instance, you must specify the secrets secret
  96    from <literal>config/secrets.yml</literal> located in your GitLab
  97    state folder.
  98   </para>
  99
 100   <para>
 101     When <literal>incoming_mail.enabled</literal> is set to <literal>true</literal>
 102     in <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> an additional
 103     service called <literal>gitlab-mailroom</literal> is enabled for fetching incoming mail.
 104   </para>
 105
 106   <para>
 107    Refer to <xref linkend="ch-options" /> for all available configuration
 108    options for the
 109    <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.
 110   </para>
 111  </section>
 112  <section xml:id="module-services-gitlab-maintenance">
 113   <title>Maintenance</title>
 114
 115   <section xml:id="module-services-gitlab-maintenance-backups">
 116    <title>Backups</title>
 117    <para>
 118      Backups can be configured with the options in <link
 119      linkend="opt-services.gitlab.backup.keepTime">services.gitlab.backup</link>. Use
 120      the <link
 121      linkend="opt-services.gitlab.backup.startAt">services.gitlab.backup.startAt</link>
 122      option to configure regular backups.
 123    </para>
 124
 125    <para>
 126      To run a manual backup, start the <literal>gitlab-backup</literal> service:
 127 <screen>
 128 <prompt>$ </prompt>systemctl start gitlab-backup.service
 129 </screen>
 130    </para>
 131   </section>
 132
 133   <section xml:id="module-services-gitlab-maintenance-rake">
 134    <title>Rake tasks</title>
 135
 136    <para>
 137     You can run GitLab's rake tasks with <literal>gitlab-rake</literal>
 138     which will be available on the system when GitLab is enabled. You
 139     will have to run the command as the user that you configured to run
 140     GitLab with.
 141    </para>
 142
 143    <para>
 144     A list of all availabe rake tasks can be obtained by running:
 145 <screen>
 146 <prompt>$ </prompt>sudo -u git -H gitlab-rake -T
 147 </screen>
 148    </para>
 149   </section>
 150  </section>
 151 </chapter>