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```
14services.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
30GitLab depends on both PostgreSQL and Redis and will automatically enable
31both services. In the case of PostgreSQL, a database and a role will be
32created.
33
34The default state dir is `/var/gitlab/state`. This is where
35all data like the repositories and uploads will be stored.
36
37A basic configuration with some custom settings could look like this:
38```
39services.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
70If you're setting up a new GitLab instance, generate new
71secrets. You for instance use
72`tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 > /var/keys/gitlab/db` to
73generate a new db secret. Make sure the files can be read by, and
74only by, the user specified by
75[services.gitlab.user](#opt-services.gitlab.user). GitLab
76encrypts sensitive data stored in the database. If you're restoring
77an existing GitLab instance, you must specify the secrets secret
78from `config/secrets.yml` located in your GitLab
79state folder.
80
81When `incoming_mail.enabled` is set to `true`
82in [extraConfig](#opt-services.gitlab.extraConfig) an additional
83service called `gitlab-mailroom` is enabled for fetching incoming mail.
84
85Refer to [](#ch-options) for all available configuration
86options 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
92Backups can be configured with the options in
93[services.gitlab.backup](#opt-services.gitlab.backup.keepTime). Use
94the [services.gitlab.backup.startAt](#opt-services.gitlab.backup.startAt)
95option to configure regular backups.
96
97To 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
104You can run GitLab's rake tasks with `gitlab-rake`
105which will be available on the system when GitLab is enabled. You
106will have to run the command as the user that you configured to run
107GitLab with.
108
109A list of all available rake tasks can be obtained by running:
110```ShellSession
111$ sudo -u git -H gitlab-rake -T
112```