diff options
Diffstat (limited to 'nixos/modules/services/misc/gitlab.xml')
-rw-r--r-- | nixos/modules/services/misc/gitlab.xml | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/nixos/modules/services/misc/gitlab.xml b/nixos/modules/services/misc/gitlab.xml new file mode 100644 index 00000000000..40424c5039a --- /dev/null +++ b/nixos/modules/services/misc/gitlab.xml @@ -0,0 +1,151 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="module-services-gitlab"> + <title>GitLab</title> + <para> + GitLab is a feature-rich git hosting service. + </para> + <section xml:id="module-services-gitlab-prerequisites"> + <title>Prerequisites</title> + + <para> + The <literal>gitlab</literal> service exposes only an Unix socket at + <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to + configure a webserver to proxy HTTP requests to the socket. + </para> + + <para> + For instance, the following configuration could be used to use nginx as + frontend proxy: +<programlisting> +<link linkend="opt-services.nginx.enable">services.nginx</link> = { + <link linkend="opt-services.nginx.enable">enable</link> = true; + <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true; + <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true; + <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true; + <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true; + <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link>."git.example.com" = { + <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true; + <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; + <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/".proxyPass</link> = "http://unix:/run/gitlab/gitlab-workhorse.socket"; + }; +}; +</programlisting> + </para> + </section> + <section xml:id="module-services-gitlab-configuring"> + <title>Configuring</title> + + <para> + 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. + </para> + + <para> + The default state dir is <literal>/var/gitlab/state</literal>. This is where + all data like the repositories and uploads will be stored. + </para> + + <para> + A basic configuration with some custom settings could look like this: +<programlisting> +services.gitlab = { + <link linkend="opt-services.gitlab.enable">enable</link> = true; + <link linkend="opt-services.gitlab.databasePasswordFile">databasePasswordFile</link> = "/var/keys/gitlab/db_password"; + <link linkend="opt-services.gitlab.initialRootPasswordFile">initialRootPasswordFile</link> = "/var/keys/gitlab/root_password"; + <link linkend="opt-services.gitlab.https">https</link> = true; + <link linkend="opt-services.gitlab.host">host</link> = "git.example.com"; + <link linkend="opt-services.gitlab.port">port</link> = 443; + <link linkend="opt-services.gitlab.user">user</link> = "git"; + <link linkend="opt-services.gitlab.group">group</link> = "git"; + smtp = { + <link linkend="opt-services.gitlab.smtp.enable">enable</link> = true; + <link linkend="opt-services.gitlab.smtp.address">address</link> = "localhost"; + <link linkend="opt-services.gitlab.smtp.port">port</link> = 25; + }; + secrets = { + <link linkend="opt-services.gitlab.secrets.dbFile">dbFile</link> = "/var/keys/gitlab/db"; + <link linkend="opt-services.gitlab.secrets.secretFile">secretFile</link> = "/var/keys/gitlab/secret"; + <link linkend="opt-services.gitlab.secrets.otpFile">otpFile</link> = "/var/keys/gitlab/otp"; + <link linkend="opt-services.gitlab.secrets.jwsFile">jwsFile</link> = "/var/keys/gitlab/jws"; + }; + <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> = { + 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; }; + }; + }; +}; +</programlisting> + </para> + + <para> + If you're setting up a new GitLab instance, generate new + secrets. You for instance use <literal>tr -dc A-Za-z0-9 < + /dev/urandom | head -c 128 > /var/keys/gitlab/db</literal> to + generate a new db secret. Make sure the files can be read by, and + only by, the user specified by <link + linkend="opt-services.gitlab.user">services.gitlab.user</link>. GitLab + encrypts sensitive data stored in the database. If you're restoring + an existing GitLab instance, you must specify the secrets secret + from <literal>config/secrets.yml</literal> located in your GitLab + state folder. + </para> + + <para> + When <literal>incoming_mail.enabled</literal> is set to <literal>true</literal> + in <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> an additional + service called <literal>gitlab-mailroom</literal> is enabled for fetching incoming mail. + </para> + + <para> + Refer to <xref linkend="ch-options" /> for all available configuration + options for the + <link linkend="opt-services.gitlab.enable">services.gitlab</link> module. + </para> + </section> + <section xml:id="module-services-gitlab-maintenance"> + <title>Maintenance</title> + + <section xml:id="module-services-gitlab-maintenance-backups"> + <title>Backups</title> + <para> + Backups can be configured with the options in <link + linkend="opt-services.gitlab.backup.keepTime">services.gitlab.backup</link>. Use + the <link + linkend="opt-services.gitlab.backup.startAt">services.gitlab.backup.startAt</link> + option to configure regular backups. + </para> + + <para> + To run a manual backup, start the <literal>gitlab-backup</literal> service: +<screen> +<prompt>$ </prompt>systemctl start gitlab-backup.service +</screen> + </para> + </section> + + <section xml:id="module-services-gitlab-maintenance-rake"> + <title>Rake tasks</title> + + <para> + You can run GitLab's rake tasks with <literal>gitlab-rake</literal> + 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. + </para> + + <para> + A list of all availabe rake tasks can be obtained by running: +<screen> +<prompt>$ </prompt>sudo -u git -H gitlab-rake -T +</screen> + </para> + </section> + </section> +</chapter> |