summary refs log tree commit diff
path: root/nixos/modules/services/misc/gitlab.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/modules/services/misc/gitlab.xml')
-rw-r--r--nixos/modules/services/misc/gitlab.xml151
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 &lt;
+   /dev/urandom | head -c 128 &gt; /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>