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