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-gitlab">
6
7<title>Gitlab</title>
8
9<para>Gitlab is a feature-rich git hosting service.</para>
10
11<section><title>Prerequisites</title>
12
13<para>The gitlab service exposes only an Unix socket at
14<literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a
15webserver to proxy HTTP requests to the socket.</para>
16
17<para>For instance, the following configuration could be used to use nginx as
18 frontend proxy:
19
20<programlisting>
21 services.nginx = {
22 enable = true;
23 recommendedGzipSettings = true;
24 recommendedOptimisation = true;
25 recommendedProxySettings = true;
26 recommendedTlsSettings = true;
27 virtualHosts."git.example.com" = {
28 enableACME = true;
29 forceSSL = true;
30 locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
31 };
32 };
33'';
34</programlisting>
35</para>
36
37</section>
38
39<section><title>Configuring</title>
40
41<para>Gitlab depends on both PostgreSQL and Redis and will automatically enable
42both services. In the case of PostgreSQL, a database and a role will be created.
43</para>
44
45<para>The default state dir is <literal>/var/gitlab/state</literal>. This is where
46all data like the repositories and uploads will be stored.</para>
47
48<para>A basic configuration with some custom settings could look like this:
49
50<programlisting>
51services.gitlab = {
52 enable = true;
53 databasePassword = "eXaMpl3";
54 initialRootPassword = "UseNixOS!";
55 https = true;
56 host = "git.example.com";
57 port = 443;
58 user = "git";
59 group = "git";
60 smtp = {
61 enable = true;
62 address = "localhost";
63 port = 25;
64 };
65 secrets = {
66 db = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
67 secret = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
68 otp = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
69 jws = ''
70 -----BEGIN RSA PRIVATE KEY-----
71 MIIEpAIBAAKCAQEArrtx4oHKwXoqUbMNqnHgAklnnuDon3XG5LJB35yPsXKv/8GK
72 ke92wkI+s1Xkvsp8tg9BIY/7c6YK4SR07EWL+dB5qwctsWR2Q8z+/BKmTx9D99pm
73 hnsjuNIXTF7BXrx3RX6BxZpH5Vzzh9nCwWKT/JCFqtwH7afNGGL7aMf+hdaiUg/Q
74 SD05yRObioiO4iXDolsJOhrnbZvlzVHl1ZYxFJv0H6/Snc0BBA9Fl/3uj6ANpbjP
75 eXF1SnJCqT87bj46r5NdVauzaRxAsIfqHroHK4UZ98X5LjGQFGvSqTvyjPBS4I1i
76 s7VJU28ObuutHxIxSlH0ibn4HZqWmKWlTS652wIDAQABAoIBAGtPcUTTw2sJlR3x
77 4k2wfAvLexkHNbZhBdKEa5JiO5mWPuLKwUiZEY2CU7Gd6csG3oqNWcm7/IjtC7dz
78 xV8p4yp8T4yq7vQIJ93B80NqTLtBD2QTvG2RCMJEPMzJUObWxkVmyVpLQyZo7KOd
79 KE/OM+aj94OUeEYLjRkSCScz1Gvq/qFG/nAy7KPCmN9JDHuhX26WHo2Rr1OnPNT/
80 7diph0bB9F3b8gjjNTqXDrpdAqVOgR/PsjEBz6DMY+bdyMIn87q2yfmMexxRofN6
81 LulpzSaa6Yup8N8H6PzVO6KAkQuf1aQRj0sMwGk1IZEnj6I0KbuHIZkw21Nc6sf2
82 ESFySDECgYEA1PnCNn5tmLnwe62Ttmrzl20zIS3Me1gUVJ1NTfr6+ai0I9iMYU21
83 5czuAjJPm9JKQF2vY8UAaCj2ZoObtHa/anb3xsCd8NXoM3iJq5JDoXI1ldz3Y+ad
84 U/bZUg1DLRvAniTuXmw9iOTwTwPxlDIGq5k+wG2Xmi1lk7zH8ezr9BMCgYEA0gfk
85 EhgcmPH8Z5cU3YYwOdt6HSJOM0OyN4k/5gnkv+HYVoJTj02gkrJmLr+mi1ugKj46
86 7huYO9TVnrKP21tmbaSv1dp5hS3letVRIxSloEtVGXmmdvJvBRzDWos+G+KcvADi
87 fFCz6w8v9NmO40CB7y/3SxTmSiSxDQeoi9LhDBkCgYEAsPgMWm25sfOnkY2NNUIv
88 wT8bAlHlHQT2d8zx5H9NttBpR3P0ShJhuF8N0sNthSQ7ULrIN5YGHYcUH+DyLAWU
89 TuomP3/kfa+xL7vUYb269tdJEYs4AkoppxBySoz8qenqpz422D0G8M6TpIS5Y5Qi
90 GMrQ6uLl21YnlpiCaFOfSQMCgYEAmZxj1kgEQmhZrnn1LL/D7czz1vMMNrpAUhXz
91 wg9iWmSXkU3oR1sDIceQrIhHCo2M6thwyU0tXjUft93pEQocM/zLDaGoVxtmRxxV
92 J08mg8IVD3jFoyFUyWxsBIDqgAKRl38eJsXvkO+ep3mm49Z+Ma3nM+apN3j2dQ0w
93 3HLzXaECgYBFLMEAboVFwi5+MZjGvqtpg2PVTisfuJy2eYnPwHs+AXUgi/xRNFjI
94 YHEa7UBPb5TEPSzWImQpETi2P5ywcUYL1EbN/nqPWmjFnat8wVmJtV4sUpJhubF4
95 Vqm9LxIWc1uQ1q1HDCejRIxIN3aSH+wgRS3Kcj8kCTIoXd1aERb04g==
96 -----END RSA PRIVATE KEY-----
97 '';
98 };
99 extraConfig = {
100 gitlab = {
101 email_from = "gitlab-no-reply@example.com";
102 email_display_name = "Example GitLab";
103 email_reply_to = "gitlab-no-reply@example.com";
104 default_projects_features = { builds = false; };
105 };
106 };
107};
108</programlisting>
109</para>
110
111<para>If you're setting up a new Gitlab instance, generate new secrets. You
112for instance use <literal>tr -dc A-Za-z0-9 < /dev/urandom | head -c 128</literal>
113to generate a new secret. Gitlab encrypts sensitive data stored in the database.
114If you're restoring an existing Gitlab instance, you must specify the secrets
115secret from <literal>config/secrets.yml</literal> located in your Gitlab state
116folder.</para>
117
118<para>Refer to <xref linkend="ch-options" /> for all available configuration
119options for the <literal>services.gitlab</literal> module.</para>
120
121</section>
122
123<section><title>Maintenance</title>
124
125<para>You can run Gitlab's rake tasks with <literal>gitlab-rake</literal>
126which will be available on the system when gitlab is enabled. You will
127have to run the command as the user that you configured to run gitlab
128with.</para>
129
130<para>For example, to backup a Gitlab instance:
131
132<programlisting>
133$ sudo -u git -H gitlab-rake gitlab:backup:create
134</programlisting>
135
136A list of all availabe rake tasks can be obtained by running:
137
138<programlisting>
139$ sudo -u git -H gitlab-rake -T
140</programlisting>
141</para>
142
143</section>
144
145</chapter>