cbdf94c0f3
Add support for storing secrets in files outside the nix store, since files in the nix store are world-readable and secrets therefore can't be stored safely there. The old string options are kept, since they can potentially be handy for testing purposes, but their descriptions now state that they shouldn't be used in production. The manual section is updated to use the file options rather than the string options and the tests now test both.
126 lines
5.3 KiB
XML
126 lines
5.3 KiB
XML
<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 gitlab 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>
|
|
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>
|
|
|
|
<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>
|
|
For example, to backup a Gitlab instance:
|
|
<screen>
|
|
<prompt>$ </prompt>sudo -u git -H gitlab-rake gitlab:backup:create
|
|
</screen>
|
|
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>
|
|
</chapter>
|