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 <title>GitLab</title>
7 <para>
8 GitLab is a feature-rich git hosting service.
9 </para>
10 <section xml:id="module-services-gitlab-prerequisites">
11 <title>Prerequisites</title>
12
13 <para>
14 The <literal>gitlab</literal> service exposes only an Unix socket at
15 <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to
16 configure a webserver to proxy HTTP requests to the socket.
17 </para>
18
19 <para>
20 For instance, the following configuration could be used to use nginx as
21 frontend proxy:
22<programlisting>
23<link linkend="opt-services.nginx.enable">services.nginx</link> = {
24 <link linkend="opt-services.nginx.enable">enable</link> = true;
25 <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
26 <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
27 <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
28 <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
29 <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link>."git.example.com" = {
30 <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
31 <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
32 <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/".proxyPass</link> = "http://unix:/run/gitlab/gitlab-workhorse.socket";
33 };
34};
35</programlisting>
36 </para>
37 </section>
38 <section xml:id="module-services-gitlab-configuring">
39 <title>Configuring</title>
40
41 <para>
42 GitLab depends on both PostgreSQL and Redis and will automatically enable
43 both services. In the case of PostgreSQL, a database and a role will be
44 created.
45 </para>
46
47 <para>
48 The default state dir is <literal>/var/gitlab/state</literal>. This is where
49 all data like the repositories and uploads will be stored.
50 </para>
51
52 <para>
53 A basic configuration with some custom settings could look like this:
54<programlisting>
55services.gitlab = {
56 <link linkend="opt-services.gitlab.enable">enable</link> = true;
57 <link linkend="opt-services.gitlab.databasePasswordFile">databasePasswordFile</link> = "/var/keys/gitlab/db_password";
58 <link linkend="opt-services.gitlab.initialRootPasswordFile">initialRootPasswordFile</link> = "/var/keys/gitlab/root_password";
59 <link linkend="opt-services.gitlab.https">https</link> = true;
60 <link linkend="opt-services.gitlab.host">host</link> = "git.example.com";
61 <link linkend="opt-services.gitlab.port">port</link> = 443;
62 <link linkend="opt-services.gitlab.user">user</link> = "git";
63 <link linkend="opt-services.gitlab.group">group</link> = "git";
64 smtp = {
65 <link linkend="opt-services.gitlab.smtp.enable">enable</link> = true;
66 <link linkend="opt-services.gitlab.smtp.address">address</link> = "localhost";
67 <link linkend="opt-services.gitlab.smtp.port">port</link> = 25;
68 };
69 secrets = {
70 <link linkend="opt-services.gitlab.secrets.dbFile">dbFile</link> = "/var/keys/gitlab/db";
71 <link linkend="opt-services.gitlab.secrets.secretFile">secretFile</link> = "/var/keys/gitlab/secret";
72 <link linkend="opt-services.gitlab.secrets.otpFile">otpFile</link> = "/var/keys/gitlab/otp";
73 <link linkend="opt-services.gitlab.secrets.jwsFile">jwsFile</link> = "/var/keys/gitlab/jws";
74 };
75 <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> = {
76 gitlab = {
77 email_from = "gitlab-no-reply@example.com";
78 email_display_name = "Example GitLab";
79 email_reply_to = "gitlab-no-reply@example.com";
80 default_projects_features = { builds = false; };
81 };
82 };
83};
84</programlisting>
85 </para>
86
87 <para>
88 If you're setting up a new GitLab instance, generate new
89 secrets. You for instance use <literal>tr -dc A-Za-z0-9 <
90 /dev/urandom | head -c 128 > /var/keys/gitlab/db</literal> to
91 generate a new db secret. Make sure the files can be read by, and
92 only by, the user specified by <link
93 linkend="opt-services.gitlab.user">services.gitlab.user</link>. GitLab
94 encrypts sensitive data stored in the database. If you're restoring
95 an existing GitLab instance, you must specify the secrets secret
96 from <literal>config/secrets.yml</literal> located in your GitLab
97 state folder.
98 </para>
99
100 <para>
101 When <literal>incoming_mail.enabled</literal> is set to <literal>true</literal>
102 in <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> an additional
103 service called <literal>gitlab-mailroom</literal> is enabled for fetching incoming mail.
104 </para>
105
106 <para>
107 Refer to <xref linkend="ch-options" /> for all available configuration
108 options for the
109 <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.
110 </para>
111 </section>
112 <section xml:id="module-services-gitlab-maintenance">
113 <title>Maintenance</title>
114
115 <section xml:id="module-services-gitlab-maintenance-backups">
116 <title>Backups</title>
117 <para>
118 Backups can be configured with the options in <link
119 linkend="opt-services.gitlab.backup.keepTime">services.gitlab.backup</link>. Use
120 the <link
121 linkend="opt-services.gitlab.backup.startAt">services.gitlab.backup.startAt</link>
122 option to configure regular backups.
123 </para>
124
125 <para>
126 To run a manual backup, start the <literal>gitlab-backup</literal> service:
127<screen>
128<prompt>$ </prompt>systemctl start gitlab-backup.service
129</screen>
130 </para>
131 </section>
132
133 <section xml:id="module-services-gitlab-maintenance-rake">
134 <title>Rake tasks</title>
135
136 <para>
137 You can run GitLab's rake tasks with <literal>gitlab-rake</literal>
138 which will be available on the system when GitLab is enabled. You
139 will have to run the command as the user that you configured to run
140 GitLab with.
141 </para>
142
143 <para>
144 A list of all availabe rake tasks can be obtained by running:
145<screen>
146<prompt>$ </prompt>sudo -u git -H gitlab-rake -T
147</screen>
148 </para>
149 </section>
150 </section>
151</chapter>