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