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 };
70 extraConfig = {
71 gitlab = {
72 email_from = "gitlab-no-reply@example.com";
73 email_display_name = "Example GitLab";
74 email_reply_to = "gitlab-no-reply@example.com";
75 default_projects_features = { builds = false; };
76 };
77 };
78};
79</programlisting>
80</para>
81
82<para>If you're setting up a new Gitlab instance, generate new secrets. You
83for instance use <literal>tr -dc A-Za-z0-9 < /dev/urandom | head -c 128</literal>
84to generate a new secret. Gitlab encrypts sensitive data stored in the database.
85If you're restoring an existing Gitlab instance, you must specify the secrets
86secret from <literal>config/secrets.yml</literal> located in your Gitlab state
87folder.</para>
88
89<para>Refer to <xref linkend="ch-options" /> for all available configuration
90options for the <literal>services.gitlab</literal> module.</para>
91
92</section>
93
94<section><title>Maintenance</title>
95
96<para>You can run Gitlab's rake tasks with <literal>gitlab-rake</literal>
97which will be available on the system when gitlab is enabled. You will
98have to run the command as the user that you configured to run gitlab
99with.</para>
100
101<para>For example, to backup a Gitlab instance:
102
103<programlisting>
104$ sudo -u git -H gitlab-rake gitlab:backup:create
105</programlisting>
106
107A list of all availabe rake tasks can be obtained by running:
108
109<programlisting>
110$ sudo -u git -H gitlab-rake -T
111</programlisting>
112</para>
113
114</section>
115
116</chapter>