nixpkgs/nixos/modules/services/misc/gitlab.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="module-services-gitlab">

<title>Gitlab</title>

<para>Gitlab is a feature-rich git hosting service.</para>

<section><title>Prerequisites</title>

<para>The gitlab service exposes only an Unix socket at
<literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a
webserver to proxy HTTP requests to the socket.</para>

<para>For instance, the following configuration could be used to use nginx as
    frontend proxy:

<programlisting>
<link linkend="opt-services.nginx.enable">services.nginx</link> = {
  <link linkend="opt-services.nginx.enable">enable</link> = true;
  <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
  <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
  <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
  <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
  <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link>."git.example.com" = {
    <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
    <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
    <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/".proxyPass</link> = "http://unix:/run/gitlab/gitlab-workhorse.socket";
  };
};
</programlisting>
</para>

</section>

<section><title>Configuring</title>

<para>Gitlab depends on both PostgreSQL and Redis and will automatically enable
both services. In the case of PostgreSQL, a database and a role will be created.
</para>

<para>The default state dir is <literal>/var/gitlab/state</literal>. This is where
all data like the repositories and uploads will be stored.</para>

<para>A basic configuration with some custom settings could look like this:

<programlisting>
services.gitlab = {
  <link linkend="opt-services.gitlab.enable">enable</link> = true;
  <link linkend="opt-services.gitlab.databasePassword">databasePassword</link> = "eXaMpl3";
  <link linkend="opt-services.gitlab.initialRootPassword">initialRootPassword</link> = "UseNixOS!";
  <link linkend="opt-services.gitlab.https">https</link> = true;
  <link linkend="opt-services.gitlab.host">host</link> = "git.example.com";
  <link linkend="opt-services.gitlab.port">port</link> = 443;
  <link linkend="opt-services.gitlab.user">user</link> = "git";
  <link linkend="opt-services.gitlab.group">group</link> = "git";
  smtp = {
    <link linkend="opt-services.gitlab.smtp.enable">enable</link> = true;
    <link linkend="opt-services.gitlab.smtp.address">address</link> = "localhost";
    <link linkend="opt-services.gitlab.smtp.port">port</link> = 25;
  };
  secrets = {
    <link linkend="opt-services.gitlab.secrets.db">db</link> = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
    <link linkend="opt-services.gitlab.secrets.secret">secret</link> = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
    <link linkend="opt-services.gitlab.secrets.otp">otp</link> = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
    <link linkend="opt-services.gitlab.secrets.jws">jws</link> = ''
      -----BEGIN RSA PRIVATE KEY-----
      MIIEpAIBAAKCAQEArrtx4oHKwXoqUbMNqnHgAklnnuDon3XG5LJB35yPsXKv/8GK
      ke92wkI+s1Xkvsp8tg9BIY/7c6YK4SR07EWL+dB5qwctsWR2Q8z+/BKmTx9D99pm
      hnsjuNIXTF7BXrx3RX6BxZpH5Vzzh9nCwWKT/JCFqtwH7afNGGL7aMf+hdaiUg/Q
      SD05yRObioiO4iXDolsJOhrnbZvlzVHl1ZYxFJv0H6/Snc0BBA9Fl/3uj6ANpbjP
      eXF1SnJCqT87bj46r5NdVauzaRxAsIfqHroHK4UZ98X5LjGQFGvSqTvyjPBS4I1i
      s7VJU28ObuutHxIxSlH0ibn4HZqWmKWlTS652wIDAQABAoIBAGtPcUTTw2sJlR3x
      4k2wfAvLexkHNbZhBdKEa5JiO5mWPuLKwUiZEY2CU7Gd6csG3oqNWcm7/IjtC7dz
      xV8p4yp8T4yq7vQIJ93B80NqTLtBD2QTvG2RCMJEPMzJUObWxkVmyVpLQyZo7KOd
      KE/OM+aj94OUeEYLjRkSCScz1Gvq/qFG/nAy7KPCmN9JDHuhX26WHo2Rr1OnPNT/
      7diph0bB9F3b8gjjNTqXDrpdAqVOgR/PsjEBz6DMY+bdyMIn87q2yfmMexxRofN6
      LulpzSaa6Yup8N8H6PzVO6KAkQuf1aQRj0sMwGk1IZEnj6I0KbuHIZkw21Nc6sf2
      ESFySDECgYEA1PnCNn5tmLnwe62Ttmrzl20zIS3Me1gUVJ1NTfr6+ai0I9iMYU21
      5czuAjJPm9JKQF2vY8UAaCj2ZoObtHa/anb3xsCd8NXoM3iJq5JDoXI1ldz3Y+ad
      U/bZUg1DLRvAniTuXmw9iOTwTwPxlDIGq5k+wG2Xmi1lk7zH8ezr9BMCgYEA0gfk
      EhgcmPH8Z5cU3YYwOdt6HSJOM0OyN4k/5gnkv+HYVoJTj02gkrJmLr+mi1ugKj46
      7huYO9TVnrKP21tmbaSv1dp5hS3letVRIxSloEtVGXmmdvJvBRzDWos+G+KcvADi
      fFCz6w8v9NmO40CB7y/3SxTmSiSxDQeoi9LhDBkCgYEAsPgMWm25sfOnkY2NNUIv
      wT8bAlHlHQT2d8zx5H9NttBpR3P0ShJhuF8N0sNthSQ7ULrIN5YGHYcUH+DyLAWU
      TuomP3/kfa+xL7vUYb269tdJEYs4AkoppxBySoz8qenqpz422D0G8M6TpIS5Y5Qi
      GMrQ6uLl21YnlpiCaFOfSQMCgYEAmZxj1kgEQmhZrnn1LL/D7czz1vMMNrpAUhXz
      wg9iWmSXkU3oR1sDIceQrIhHCo2M6thwyU0tXjUft93pEQocM/zLDaGoVxtmRxxV
      J08mg8IVD3jFoyFUyWxsBIDqgAKRl38eJsXvkO+ep3mm49Z+Ma3nM+apN3j2dQ0w
      3HLzXaECgYBFLMEAboVFwi5+MZjGvqtpg2PVTisfuJy2eYnPwHs+AXUgi/xRNFjI
      YHEa7UBPb5TEPSzWImQpETi2P5ywcUYL1EbN/nqPWmjFnat8wVmJtV4sUpJhubF4
      Vqm9LxIWc1uQ1q1HDCejRIxIN3aSH+wgRS3Kcj8kCTIoXd1aERb04g==
      -----END RSA PRIVATE KEY-----
    '';
  };
  <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> = {
    gitlab = {
      email_from = "gitlab-no-reply@example.com";
      email_display_name = "Example GitLab";
      email_reply_to = "gitlab-no-reply@example.com";
      default_projects_features = { builds = false; };
    };
  };
};
</programlisting>
</para>

<para>If you're setting up a new Gitlab instance, generate new secrets. You
for instance use <literal>tr -dc A-Za-z0-9 &lt; /dev/urandom | head -c 128</literal>
to generate a new secret. Gitlab encrypts sensitive data stored in the database.
If you're restoring an existing Gitlab instance, you must specify the secrets
secret from <literal>config/secrets.yml</literal> located in your Gitlab state
folder.</para>

<para>Refer to <xref linkend="ch-options" /> for all available configuration
options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.</para>

</section>

<section><title>Maintenance</title>

<para>You can run Gitlab's rake tasks with <literal>gitlab-rake</literal>
which will be available on the system when gitlab is enabled. You will
have to run the command as the user that you configured to run gitlab
with.</para>

<para>For example, to backup a Gitlab instance:

<programlisting>
$ sudo -u git -H gitlab-rake gitlab:backup:create
</programlisting>

A list of all availabe rake tasks can be obtained by running:

<programlisting>
$ sudo -u git -H gitlab-rake -T
</programlisting>
</para>

</section>

</chapter>