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