nixos/modules/services/misc/gitlab.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-gitlab">
  <title>GitLab</title>
  <para>
    GitLab is a feature-rich git hosting service.
  </para>
  <section xml:id="module-services-gitlab-prerequisites">
    <title>Prerequisites</title>
    <para>
      The <literal>gitlab</literal> 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:
    </para>
    <programlisting>
services.nginx = {
  enable = true;
  recommendedGzipSettings = true;
  recommendedOptimisation = true;
  recommendedProxySettings = true;
  recommendedTlsSettings = true;
  virtualHosts.&quot;git.example.com&quot; = {
    enableACME = true;
    forceSSL = true;
    locations.&quot;/&quot;.proxyPass = &quot;http://unix:/run/gitlab/gitlab-workhorse.socket&quot;;
  };
};
</programlisting>
  </section>
  <section xml:id="module-services-gitlab-configuring">
    <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:
    </para>
    <programlisting>
services.gitlab = {
  enable = true;
  databasePasswordFile = &quot;/var/keys/gitlab/db_password&quot;;
  initialRootPasswordFile = &quot;/var/keys/gitlab/root_password&quot;;
  https = true;
  host = &quot;git.example.com&quot;;
  port = 443;
  user = &quot;git&quot;;
  group = &quot;git&quot;;
  smtp = {
    enable = true;
    address = &quot;localhost&quot;;
    port = 25;
  };
  secrets = {
    dbFile = &quot;/var/keys/gitlab/db&quot;;
    secretFile = &quot;/var/keys/gitlab/secret&quot;;
    otpFile = &quot;/var/keys/gitlab/otp&quot;;
    jwsFile = &quot;/var/keys/gitlab/jws&quot;;
  };
  extraConfig = {
    gitlab = {
      email_from = &quot;gitlab-no-reply@example.com&quot;;
      email_display_name = &quot;Example GitLab&quot;;
      email_reply_to = &quot;gitlab-no-reply@example.com&quot;;
      default_projects_features = { builds = false; };
    };
  };
};
</programlisting>
    <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 &gt; /var/keys/gitlab/db</literal>
      to generate a new db secret. Make sure the files can be read by,
      and only by, the user specified by
      <link linkend="opt-services.gitlab.user">services.gitlab.user</link>.
      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>
      When <literal>incoming_mail.enabled</literal> is set to
      <literal>true</literal> in
      <link linkend="opt-services.gitlab.extraConfig">extraConfig</link>
      an additional service called <literal>gitlab-mailroom</literal> is
      enabled for fetching incoming mail.
    </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 xml:id="module-services-gitlab-maintenance">
    <title>Maintenance</title>
    <section xml:id="module-services-gitlab-maintenance-backups">
      <title>Backups</title>
      <para>
        Backups can be configured with the options in
        <link linkend="opt-services.gitlab.backup.keepTime">services.gitlab.backup</link>.
        Use the
        <link linkend="opt-services.gitlab.backup.startAt">services.gitlab.backup.startAt</link>
        option to configure regular backups.
      </para>
      <para>
        To run a manual backup, start the
        <literal>gitlab-backup</literal> service:
      </para>
      <programlisting>
$ systemctl start gitlab-backup.service
</programlisting>
    </section>
    <section xml:id="module-services-gitlab-maintenance-rake">
      <title>Rake tasks</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>
        A list of all available rake tasks can be obtained by running:
      </para>
      <programlisting>
$ sudo -u git -H gitlab-rake -T
</programlisting>
    </section>
  </section>
</chapter>