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