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