From 73d8b04f3056aaff635885f9dacb253c75239656 Mon Sep 17 00:00:00 2001 From: pennae Date: Tue, 3 Jan 2023 04:54:39 +0100 Subject: [PATCH] nixos/gitlab: convert manual chapter to MD --- nixos/modules/services/misc/gitlab.md | 112 ++++++++++++ nixos/modules/services/misc/gitlab.nix | 2 + nixos/modules/services/misc/gitlab.xml | 226 ++++++++++++------------- 3 files changed, 222 insertions(+), 118 deletions(-) create mode 100644 nixos/modules/services/misc/gitlab.md diff --git a/nixos/modules/services/misc/gitlab.md b/nixos/modules/services/misc/gitlab.md new file mode 100644 index 000000000000..916b23584ed0 --- /dev/null +++ b/nixos/modules/services/misc/gitlab.md @@ -0,0 +1,112 @@ +# GitLab {#module-services-gitlab} + +GitLab is a feature-rich git hosting service. + +## Prerequisites {#module-services-gitlab-prerequisites} + +The `gitlab` service exposes only an Unix socket at +`/run/gitlab/gitlab-workhorse.socket`. You need to +configure a webserver to proxy HTTP requests to the socket. + +For instance, the following configuration could be used to use nginx as +frontend proxy: +``` +services.nginx = { + enable = true; + recommendedGzipSettings = true; + recommendedOptimisation = true; + recommendedProxySettings = true; + recommendedTlsSettings = true; + virtualHosts."git.example.com" = { + enableACME = true; + forceSSL = true; + locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket"; + }; +}; +``` + +## Configuring {#module-services-gitlab-configuring} + +GitLab depends on both PostgreSQL and Redis and will automatically enable +both services. In the case of PostgreSQL, a database and a role will be +created. + +The default state dir is `/var/gitlab/state`. This is where +all data like the repositories and uploads will be stored. + +A basic configuration with some custom settings could look like this: +``` +services.gitlab = { + enable = true; + databasePasswordFile = "/var/keys/gitlab/db_password"; + initialRootPasswordFile = "/var/keys/gitlab/root_password"; + https = true; + host = "git.example.com"; + port = 443; + user = "git"; + group = "git"; + smtp = { + enable = true; + address = "localhost"; + port = 25; + }; + secrets = { + dbFile = "/var/keys/gitlab/db"; + secretFile = "/var/keys/gitlab/secret"; + otpFile = "/var/keys/gitlab/otp"; + jwsFile = "/var/keys/gitlab/jws"; + }; + extraConfig = { + gitlab = { + email_from = "gitlab-no-reply@example.com"; + email_display_name = "Example GitLab"; + email_reply_to = "gitlab-no-reply@example.com"; + default_projects_features = { builds = false; }; + }; + }; +}; +``` + +If you're setting up a new GitLab instance, generate new +secrets. You for instance use +`tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 > /var/keys/gitlab/db` to +generate a new db secret. Make sure the files can be read by, and +only by, the user specified by +[services.gitlab.user](#opt-services.gitlab.user). GitLab +encrypts sensitive data stored in the database. If you're restoring +an existing GitLab instance, you must specify the secrets secret +from `config/secrets.yml` located in your GitLab +state folder. + +When `incoming_mail.enabled` is set to `true` +in [extraConfig](#opt-services.gitlab.extraConfig) an additional +service called `gitlab-mailroom` is enabled for fetching incoming mail. + +Refer to [](#ch-options) for all available configuration +options for the [services.gitlab](#opt-services.gitlab.enable) module. + +## Maintenance {#module-services-gitlab-maintenance} + +### Backups {#module-services-gitlab-maintenance-backups} + +Backups can be configured with the options in +[services.gitlab.backup](#opt-services.gitlab.backup.keepTime). Use +the [services.gitlab.backup.startAt](#opt-services.gitlab.backup.startAt) +option to configure regular backups. + +To run a manual backup, start the `gitlab-backup` service: +```ShellSession +$ systemctl start gitlab-backup.service +``` + +### Rake tasks {#module-services-gitlab-maintenance-rake} + +You can run GitLab's rake tasks with `gitlab-rake` +which will be available on the system when GitLab is enabled. You +will have to run the command as the user that you configured to run +GitLab with. + +A list of all available rake tasks can be obtained by running: +```ShellSession +$ sudo -u git -H gitlab-rake -T +``` diff --git a/nixos/modules/services/misc/gitlab.nix b/nixos/modules/services/misc/gitlab.nix index e7c707228f1b..d5dfc22dc226 100644 --- a/nixos/modules/services/misc/gitlab.nix +++ b/nixos/modules/services/misc/gitlab.nix @@ -1502,6 +1502,8 @@ in { }; + # Don't edit the docbook xml directly, edit the md and generate it: + # `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` meta.doc = ./gitlab.xml; } diff --git a/nixos/modules/services/misc/gitlab.xml b/nixos/modules/services/misc/gitlab.xml index a9f8d5fd7219..42e26afa824b 100644 --- a/nixos/modules/services/misc/gitlab.xml +++ b/nixos/modules/services/misc/gitlab.xml @@ -1,151 +1,141 @@ - - GitLab - - GitLab is a feature-rich git hosting service. - -
- Prerequisites - + + GitLab - The gitlab service exposes only an Unix socket at - /run/gitlab/gitlab-workhorse.socket. You need to - configure a webserver to proxy HTTP requests to the socket. + GitLab is a feature-rich git hosting service. - - - For instance, the following configuration could be used to use nginx as - frontend proxy: - +
+ Prerequisites + + The gitlab service exposes only an Unix socket + at /run/gitlab/gitlab-workhorse.socket. You + need to configure a webserver to proxy HTTP requests to the + socket. + + + For instance, the following configuration could be used to use + nginx as frontend proxy: + + services.nginx = { enable = true; recommendedGzipSettings = true; recommendedOptimisation = true; recommendedProxySettings = true; recommendedTlsSettings = true; - virtualHosts."git.example.com" = { + virtualHosts."git.example.com" = { enableACME = true; forceSSL = true; - locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket"; + locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket"; }; }; - -
-
- Configuring - - - GitLab depends on both PostgreSQL and Redis and will automatically enable - both services. In the case of PostgreSQL, a database and a role will be - created. - - - - The default state dir is /var/gitlab/state. This is where - all data like the repositories and uploads will be stored. - - - - A basic configuration with some custom settings could look like this: - +
+
+ Configuring + + GitLab depends on both PostgreSQL and Redis and will automatically + enable both services. In the case of PostgreSQL, a database and a + role will be created. + + + The default state dir is /var/gitlab/state. + This is where all data like the repositories and uploads will be + stored. + + + A basic configuration with some custom settings could look like + this: + + services.gitlab = { enable = true; - databasePasswordFile = "/var/keys/gitlab/db_password"; - initialRootPasswordFile = "/var/keys/gitlab/root_password"; + databasePasswordFile = "/var/keys/gitlab/db_password"; + initialRootPasswordFile = "/var/keys/gitlab/root_password"; https = true; - host = "git.example.com"; + host = "git.example.com"; port = 443; - user = "git"; - group = "git"; + user = "git"; + group = "git"; smtp = { enable = true; - address = "localhost"; + address = "localhost"; port = 25; }; secrets = { - dbFile = "/var/keys/gitlab/db"; - secretFile = "/var/keys/gitlab/secret"; - otpFile = "/var/keys/gitlab/otp"; - jwsFile = "/var/keys/gitlab/jws"; + dbFile = "/var/keys/gitlab/db"; + secretFile = "/var/keys/gitlab/secret"; + otpFile = "/var/keys/gitlab/otp"; + jwsFile = "/var/keys/gitlab/jws"; }; extraConfig = { gitlab = { - email_from = "gitlab-no-reply@example.com"; - email_display_name = "Example GitLab"; - email_reply_to = "gitlab-no-reply@example.com"; + email_from = "gitlab-no-reply@example.com"; + email_display_name = "Example GitLab"; + email_reply_to = "gitlab-no-reply@example.com"; default_projects_features = { builds = false; }; }; }; }; - - - - If you're setting up a new GitLab instance, generate new - secrets. You for instance use tr -dc A-Za-z0-9 < - /dev/urandom | head -c 128 > /var/keys/gitlab/db to - generate a new db secret. Make sure the files can be read by, and - only by, the user specified by services.gitlab.user. GitLab - encrypts sensitive data stored in the database. If you're restoring - an existing GitLab instance, you must specify the secrets secret - from config/secrets.yml located in your GitLab - state folder. - - - - When incoming_mail.enabled is set to true - in extraConfig an additional - service called gitlab-mailroom is enabled for fetching incoming mail. - - - - Refer to for all available configuration - options for the - services.gitlab module. - -
-
- Maintenance - -
- Backups - - Backups can be configured with the options in services.gitlab.backup. Use - the services.gitlab.backup.startAt - option to configure regular backups. - - - - To run a manual backup, start the gitlab-backup service: - -$ systemctl start gitlab-backup.service - - + + If you're setting up a new GitLab instance, generate new secrets. + You for instance use + tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 > /var/keys/gitlab/db + to generate a new db secret. Make sure the files can be read by, + and only by, the user specified by + services.gitlab.user. + GitLab encrypts sensitive data stored in the database. If you're + restoring an existing GitLab instance, you must specify the + secrets secret from config/secrets.yml located + in your GitLab state folder. + + + When incoming_mail.enabled is set to + true in + extraConfig + an additional service called gitlab-mailroom is + enabled for fetching incoming mail. + + + Refer to for all available + configuration options for the + services.gitlab + module. +
- -
- Rake tasks - - - You can run GitLab's rake tasks with gitlab-rake - which will be available on the system when GitLab is enabled. You - will have to run the command as the user that you configured to run - GitLab with. - - - - A list of all available rake tasks can be obtained by running: - -$ sudo -u git -H gitlab-rake -T - - +
+ Maintenance +
+ Backups + + Backups can be configured with the options in + services.gitlab.backup. + Use the + services.gitlab.backup.startAt + option to configure regular backups. + + + To run a manual backup, start the + gitlab-backup service: + + +$ systemctl start gitlab-backup.service + +
+
+ Rake tasks + + You can run GitLab's rake tasks with + gitlab-rake which will be available on the + system when GitLab is enabled. You will have to run the command + as the user that you configured to run GitLab with. + + + A list of all available rake tasks can be obtained by running: + + +$ sudo -u git -H gitlab-rake -T + +
-