commit 73d8b04f3056aaff635885f9dacb253c75239656 · pyrox.dev/nixpkgs

+112

nixos/modules/services/misc/gitlab.md

···

       1
       1
       +
       # GitLab {#module-services-gitlab}

     

       2
       2
       +
       

     

       3
       3
       +
       GitLab is a feature-rich git hosting service.

     

       4
       4
       +
       

     

       5
       5
       +
       ## Prerequisites {#module-services-gitlab-prerequisites}

     

       6
       6
       +
       

     

       7
       7
       +
       The `gitlab` service exposes only an Unix socket at

     

       8
       8
       +
       `/run/gitlab/gitlab-workhorse.socket`. You need to

     

       9
       9
       +
       configure a webserver to proxy HTTP requests to the socket.

     

       10
       10
       +
       

     

       11
       11
       +
       For instance, the following configuration could be used to use nginx as

     

       12
       12
       +
       frontend proxy:

     

       13
       13
       +
       ```

     

       14
       14
       +
       services.nginx = {

     

       15
       15
       +
         enable = true;

     

       16
       16
       +
         recommendedGzipSettings = true;

     

       17
       17
       +
         recommendedOptimisation = true;

     

       18
       18
       +
         recommendedProxySettings = true;

     

       19
       19
       +
         recommendedTlsSettings = true;

     

       20
       20
       +
         virtualHosts."git.example.com" = {

     

       21
       21
       +
           enableACME = true;

     

       22
       22
       +
           forceSSL = true;

     

       23
       23
       +
           locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";

     

       24
       24
       +
         };

     

       25
       25
       +
       };

     

       26
       26
       +
       ```

     

       27
       27
       +
       

     

       28
       28
       +
       ## Configuring {#module-services-gitlab-configuring}

     

       29
       29
       +
       

     

       30
       30
       +
       GitLab depends on both PostgreSQL and Redis and will automatically enable

     

       31
       31
       +
       both services. In the case of PostgreSQL, a database and a role will be

     

       32
       32
       +
       created.

     

       33
       33
       +
       

     

       34
       34
       +
       The default state dir is `/var/gitlab/state`. This is where

     

       35
       35
       +
       all data like the repositories and uploads will be stored.

     

       36
       36
       +
       

     

       37
       37
       +
       A basic configuration with some custom settings could look like this:

     

       38
       38
       +
       ```

     

       39
       39
       +
       services.gitlab = {

     

       40
       40
       +
         enable = true;

     

       41
       41
       +
         databasePasswordFile = "/var/keys/gitlab/db_password";

     

       42
       42
       +
         initialRootPasswordFile = "/var/keys/gitlab/root_password";

     

       43
       43
       +
         https = true;

     

       44
       44
       +
         host = "git.example.com";

     

       45
       45
       +
         port = 443;

     

       46
       46
       +
         user = "git";

     

       47
       47
       +
         group = "git";

     

       48
       48
       +
         smtp = {

     

       49
       49
       +
           enable = true;

     

       50
       50
       +
           address = "localhost";

     

       51
       51
       +
           port = 25;

     

       52
       52
       +
         };

     

       53
       53
       +
         secrets = {

     

       54
       54
       +
           dbFile = "/var/keys/gitlab/db";

     

       55
       55
       +
           secretFile = "/var/keys/gitlab/secret";

     

       56
       56
       +
           otpFile = "/var/keys/gitlab/otp";

     

       57
       57
       +
           jwsFile = "/var/keys/gitlab/jws";

     

       58
       58
       +
         };

     

       59
       59
       +
         extraConfig = {

     

       60
       60
       +
           gitlab = {

     

       61
       61
       +
             email_from = "gitlab-no-reply@example.com";

     

       62
       62
       +
             email_display_name = "Example GitLab";

     

       63
       63
       +
             email_reply_to = "gitlab-no-reply@example.com";

     

       64
       64
       +
             default_projects_features = { builds = false; };

     

       65
       65
       +
           };

     

       66
       66
       +
         };

     

       67
       67
       +
       };

     

       68
       68
       +
       ```

     

       69
       69
       +
       

     

       70
       70
       +
       If you're setting up a new GitLab instance, generate new

     

       71
       71
       +
       secrets. You for instance use

     

       72
       72
       +
       `tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 > /var/keys/gitlab/db` to

     

       73
       73
       +
       generate a new db secret. Make sure the files can be read by, and

     

       74
       74
       +
       only by, the user specified by

     

       75
       75
       +
       [services.gitlab.user](#opt-services.gitlab.user). GitLab

     

       76
       76
       +
       encrypts sensitive data stored in the database. If you're restoring

     

       77
       77
       +
       an existing GitLab instance, you must specify the secrets secret

     

       78
       78
       +
       from `config/secrets.yml` located in your GitLab

     

       79
       79
       +
       state folder.

     

       80
       80
       +
       

     

       81
       81
       +
       When `incoming_mail.enabled` is set to `true`

     

       82
       82
       +
       in [extraConfig](#opt-services.gitlab.extraConfig) an additional

     

       83
       83
       +
       service called `gitlab-mailroom` is enabled for fetching incoming mail.

     

       84
       84
       +
       

     

       85
       85
       +
       Refer to [](#ch-options) for all available configuration

     

       86
       86
       +
       options for the [services.gitlab](#opt-services.gitlab.enable) module.

     

       87
       87
       +
       

     

       88
       88
       +
       ## Maintenance {#module-services-gitlab-maintenance}

     

       89
       89
       +
       

     

       90
       90
       +
       ### Backups {#module-services-gitlab-maintenance-backups}

     

       91
       91
       +
       

     

       92
       92
       +
       Backups can be configured with the options in

     

       93
       93
       +
       [services.gitlab.backup](#opt-services.gitlab.backup.keepTime). Use

     

       94
       94
       +
       the [services.gitlab.backup.startAt](#opt-services.gitlab.backup.startAt)

     

       95
       95
       +
       option to configure regular backups.

     

       96
       96
       +
       

     

       97
       97
       +
       To run a manual backup, start the `gitlab-backup` service:

     

       98
       98
       +
       ```ShellSession

     

       99
       99
       +
       $ systemctl start gitlab-backup.service

     

       100
       100
       +
       ```

     

       101
       101
       +
       

     

       102
       102
       +
       ### Rake tasks {#module-services-gitlab-maintenance-rake}

     

       103
       103
       +
       

     

       104
       104
       +
       You can run GitLab's rake tasks with `gitlab-rake`

     

       105
       105
       +
       which will be available on the system when GitLab is enabled. You

     

       106
       106
       +
       will have to run the command as the user that you configured to run

     

       107
       107
       +
       GitLab with.

     

       108
       108
       +
       

     

       109
       109
       +
       A list of all available rake tasks can be obtained by running:

     

       110
       110
       +
       ```ShellSession

     

       111
       111
       +
       $ sudo -u git -H gitlab-rake -T

     

       112
       112
       +
       ```

nixos/modules/services/misc/gitlab.nix

···

       1502
       1502
        
       

     

       1503
       1503
        
         };

     

       1504
       1504
        
       

     

       1505
       1505
       +
         # Don't edit the docbook xml directly, edit the md and generate it:

     

       1506
       1506
       +
         # `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`

     

       1505
       1507
        
         meta.doc = ./gitlab.xml;

     

       1506
       1508
        
       

     

       1507
       1509
        
       }

+108 -118

nixos/modules/services/misc/gitlab.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="module-services-gitlab">

     

       6
       6
       -
        <title>GitLab</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         GitLab is a feature-rich git hosting service.

     

       9
       9
       -
        </para>

     

       10
       10
       -
        <section xml:id="module-services-gitlab-prerequisites">

     

       11
       11
       -
         <title>Prerequisites</title>

     

       12
       12
       -
       

     

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-gitlab">

     

       2
       2
       +
         <title>GitLab</title>

     

       13
       3
        
         <para>

     

       14
       14
       -
          The <literal>gitlab</literal> service exposes only an Unix socket at

     

       15
       15
       -
          <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to

     

       16
       16
       -
          configure a webserver to proxy HTTP requests to the socket.

     

       4
       4
       +
           GitLab is a feature-rich git hosting service.

     

       17
       5
        
         </para>

     

       18
       18
       -
       

     

       19
       19
       -
         <para>

     

       20
       20
       -
          For instance, the following configuration could be used to use nginx as

     

       21
       21
       -
          frontend proxy:

     

       22
       22
       -
       <programlisting>

     

       6
       6
       +
         <section xml:id="module-services-gitlab-prerequisites">

     

       7
       7
       +
           <title>Prerequisites</title>

     

       8
       8
       +
           <para>

     

       9
       9
       +
             The <literal>gitlab</literal> service exposes only an Unix socket

     

       10
       10
       +
             at <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You

     

       11
       11
       +
             need to configure a webserver to proxy HTTP requests to the

     

       12
       12
       +
             socket.

     

       13
       13
       +
           </para>

     

       14
       14
       +
           <para>

     

       15
       15
       +
             For instance, the following configuration could be used to use

     

       16
       16
       +
             nginx as frontend proxy:

     

       17
       17
       +
           </para>

     

       18
       18
       +
           <programlisting>

     

       23
       19
        
       services.nginx = {

     

       24
       20
        
         enable = true;

     

       25
       21
        
         recommendedGzipSettings = true;

     

       26
       22
        
         recommendedOptimisation = true;

     

       27
       23
        
         recommendedProxySettings = true;

     

       28
       24
        
         recommendedTlsSettings = true;

     

       29
       29
       -
         virtualHosts."git.example.com" = {

     

       25
       25
       +
         virtualHosts.&quot;git.example.com&quot; = {

     

       30
       26
        
           enableACME = true;

     

       31
       27
        
           forceSSL = true;

     

       32
       32
       -
           locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";

     

       28
       28
       +
           locations.&quot;/&quot;.proxyPass = &quot;http://unix:/run/gitlab/gitlab-workhorse.socket&quot;;

     

       33
       29
        
         };

     

       34
       30
        
       };

     

       35
       31
        
       </programlisting>

     

       36
       36
       -
         </para>

     

       37
       37
       -
        </section>

     

       38
       38
       -
        <section xml:id="module-services-gitlab-configuring">

     

       39
       39
       -
         <title>Configuring</title>

     

       40
       40
       -
       

     

       41
       41
       -
         <para>

     

       42
       42
       -
          GitLab depends on both PostgreSQL and Redis and will automatically enable

     

       43
       43
       -
          both services. In the case of PostgreSQL, a database and a role will be

     

       44
       44
       -
          created.

     

       45
       45
       -
         </para>

     

       46
       46
       -
       

     

       47
       47
       -
         <para>

     

       48
       48
       -
          The default state dir is <literal>/var/gitlab/state</literal>. This is where

     

       49
       49
       -
          all data like the repositories and uploads will be stored.

     

       50
       50
       -
         </para>

     

       51
       51
       -
       

     

       52
       52
       -
         <para>

     

       53
       53
       -
          A basic configuration with some custom settings could look like this:

     

       54
       54
       -
       <programlisting>

     

       32
       32
       +
         </section>

     

       33
       33
       +
         <section xml:id="module-services-gitlab-configuring">

     

       34
       34
       +
           <title>Configuring</title>

     

       35
       35
       +
           <para>

     

       36
       36
       +
             GitLab depends on both PostgreSQL and Redis and will automatically

     

       37
       37
       +
             enable both services. In the case of PostgreSQL, a database and a

     

       38
       38
       +
             role will be created.

     

       39
       39
       +
           </para>

     

       40
       40
       +
           <para>

     

       41
       41
       +
             The default state dir is <literal>/var/gitlab/state</literal>.

     

       42
       42
       +
             This is where all data like the repositories and uploads will be

     

       43
       43
       +
             stored.

     

       44
       44
       +
           </para>

     

       45
       45
       +
           <para>

     

       46
       46
       +
             A basic configuration with some custom settings could look like

     

       47
       47
       +
             this:

     

       48
       48
       +
           </para>

     

       49
       49
       +
           <programlisting>

     

       55
       50
        
       services.gitlab = {

     

       56
       51
        
         enable = true;

     

       57
       57
       -
         databasePasswordFile = "/var/keys/gitlab/db_password";

     

       58
       58
       -
         initialRootPasswordFile = "/var/keys/gitlab/root_password";

     

       52
       52
       +
         databasePasswordFile = &quot;/var/keys/gitlab/db_password&quot;;

     

       53
       53
       +
         initialRootPasswordFile = &quot;/var/keys/gitlab/root_password&quot;;

     

       59
       54
        
         https = true;

     

       60
       60
       -
         host = "git.example.com";

     

       55
       55
       +
         host = &quot;git.example.com&quot;;

     

       61
       56
        
         port = 443;

     

       62
       62
       -
         user = "git";

     

       63
       63
       -
         group = "git";

     

       57
       57
       +
         user = &quot;git&quot;;

     

       58
       58
       +
         group = &quot;git&quot;;

     

       64
       59
        
         smtp = {

     

       65
       60
        
           enable = true;

     

       66
       66
       -
           address = "localhost";

     

       61
       61
       +
           address = &quot;localhost&quot;;

     

       67
       62
        
           port = 25;

     

       68
       63
        
         };

     

       69
       64
        
         secrets = {

     

       70
       70
       -
           dbFile = "/var/keys/gitlab/db";

     

       71
       71
       -
           secretFile = "/var/keys/gitlab/secret";

     

       72
       72
       -
           otpFile = "/var/keys/gitlab/otp";

     

       73
       73
       -
           jwsFile = "/var/keys/gitlab/jws";

     

       65
       65
       +
           dbFile = &quot;/var/keys/gitlab/db&quot;;

     

       66
       66
       +
           secretFile = &quot;/var/keys/gitlab/secret&quot;;

     

       67
       67
       +
           otpFile = &quot;/var/keys/gitlab/otp&quot;;

     

       68
       68
       +
           jwsFile = &quot;/var/keys/gitlab/jws&quot;;

     

       74
       69
        
         };

     

       75
       70
        
         extraConfig = {

     

       76
       71
        
           gitlab = {

     

       77
       77
       -
             email_from = "gitlab-no-reply@example.com";

     

       78
       78
       -
             email_display_name = "Example GitLab";

     

       79
       79
       -
             email_reply_to = "gitlab-no-reply@example.com";

     

       72
       72
       +
             email_from = &quot;gitlab-no-reply@example.com&quot;;

     

       73
       73
       +
             email_display_name = &quot;Example GitLab&quot;;

     

       74
       74
       +
             email_reply_to = &quot;gitlab-no-reply@example.com&quot;;

     

       80
       75
        
             default_projects_features = { builds = false; };

     

       81
       76
        
           };

     

       82
       77
        
         };

     

       83
       78
        
       };

     

       84
       79
        
       </programlisting>

     

       85
       85
       -
         </para>

     

       86
       86
       -
       

     

       87
       87
       -
         <para>

     

       88
       88
       -
          If you're setting up a new GitLab instance, generate new

     

       89
       89
       -
          secrets. You for instance use <literal>tr -dc A-Za-z0-9 &lt;

     

       90
       90
       -
          /dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal> to

     

       91
       91
       -
          generate a new db secret. Make sure the files can be read by, and

     

       92
       92
       -
          only by, the user specified by <link

     

       93
       93
       -
          linkend="opt-services.gitlab.user">services.gitlab.user</link>. GitLab

     

       94
       94
       -
          encrypts sensitive data stored in the database. If you're restoring

     

       95
       95
       -
          an existing GitLab instance, you must specify the secrets secret

     

       96
       96
       -
          from <literal>config/secrets.yml</literal> located in your GitLab

     

       97
       97
       -
          state folder.

     

       98
       98
       -
         </para>

     

       99
       99
       -
       

     

       100
       100
       -
         <para>

     

       101
       101
       -
           When <literal>incoming_mail.enabled</literal> is set to <literal>true</literal>

     

       102
       102
       -
           in <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> an additional

     

       103
       103
       -
           service called <literal>gitlab-mailroom</literal> is enabled for fetching incoming mail.

     

       104
       104
       -
         </para>

     

       105
       105
       -
       

     

       106
       106
       -
         <para>

     

       107
       107
       -
          Refer to <xref linkend="ch-options" /> for all available configuration

     

       108
       108
       -
          options for the

     

       109
       109
       -
          <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.

     

       110
       110
       -
         </para>

     

       111
       111
       -
        </section>

     

       112
       112
       -
        <section xml:id="module-services-gitlab-maintenance">

     

       113
       113
       -
         <title>Maintenance</title>

     

       114
       114
       -
       

     

       115
       115
       -
         <section xml:id="module-services-gitlab-maintenance-backups">

     

       116
       116
       -
          <title>Backups</title>

     

       117
       117
       -
          <para>

     

       118
       118
       -
            Backups can be configured with the options in <link

     

       119
       119
       -
            linkend="opt-services.gitlab.backup.keepTime">services.gitlab.backup</link>. Use

     

       120
       120
       -
            the <link

     

       121
       121
       -
            linkend="opt-services.gitlab.backup.startAt">services.gitlab.backup.startAt</link>

     

       122
       122
       -
            option to configure regular backups.

     

       123
       123
       -
          </para>

     

       124
       124
       -
       

     

       125
       125
       -
          <para>

     

       126
       126
       -
            To run a manual backup, start the <literal>gitlab-backup</literal> service:

     

       127
       127
       -
       <screen>

     

       128
       128
       -
       <prompt>$ </prompt>systemctl start gitlab-backup.service

     

       129
       129
       -
       </screen>

     

       130
       130
       -
          </para>

     

       80
       80
       +
           <para>

     

       81
       81
       +
             If you're setting up a new GitLab instance, generate new secrets.

     

       82
       82
       +
             You for instance use

     

       83
       83
       +
             <literal>tr -dc A-Za-z0-9 &lt; /dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal>

     

       84
       84
       +
             to generate a new db secret. Make sure the files can be read by,

     

       85
       85
       +
             and only by, the user specified by

     

       86
       86
       +
             <link linkend="opt-services.gitlab.user">services.gitlab.user</link>.

     

       87
       87
       +
             GitLab encrypts sensitive data stored in the database. If you're

     

       88
       88
       +
             restoring an existing GitLab instance, you must specify the

     

       89
       89
       +
             secrets secret from <literal>config/secrets.yml</literal> located

     

       90
       90
       +
             in your GitLab state folder.

     

       91
       91
       +
           </para>

     

       92
       92
       +
           <para>

     

       93
       93
       +
             When <literal>incoming_mail.enabled</literal> is set to

     

       94
       94
       +
             <literal>true</literal> in

     

       95
       95
       +
             <link linkend="opt-services.gitlab.extraConfig">extraConfig</link>

     

       96
       96
       +
             an additional service called <literal>gitlab-mailroom</literal> is

     

       97
       97
       +
             enabled for fetching incoming mail.

     

       98
       98
       +
           </para>

     

       99
       99
       +
           <para>

     

       100
       100
       +
             Refer to <xref linkend="ch-options"></xref> for all available

     

       101
       101
       +
             configuration options for the

     

       102
       102
       +
             <link linkend="opt-services.gitlab.enable">services.gitlab</link>

     

       103
       103
       +
             module.

     

       104
       104
       +
           </para>

     

       131
       105
        
         </section>

     

       132
       132
       -
       

     

       133
       133
       -
         <section xml:id="module-services-gitlab-maintenance-rake">

     

       134
       134
       -
          <title>Rake tasks</title>

     

       135
       135
       -
       

     

       136
       136
       -
          <para>

     

       137
       137
       -
           You can run GitLab's rake tasks with <literal>gitlab-rake</literal>

     

       138
       138
       -
           which will be available on the system when GitLab is enabled. You

     

       139
       139
       -
           will have to run the command as the user that you configured to run

     

       140
       140
       -
           GitLab with.

     

       141
       141
       -
          </para>

     

       142
       142
       -
       

     

       143
       143
       -
          <para>

     

       144
       144
       -
           A list of all available rake tasks can be obtained by running:

     

       145
       145
       -
       <screen>

     

       146
       146
       -
       <prompt>$ </prompt>sudo -u git -H gitlab-rake -T

     

       147
       147
       -
       </screen>

     

       148
       148
       -
          </para>

     

       106
       106
       +
         <section xml:id="module-services-gitlab-maintenance">

     

       107
       107
       +
           <title>Maintenance</title>

     

       108
       108
       +
           <section xml:id="module-services-gitlab-maintenance-backups">

     

       109
       109
       +
             <title>Backups</title>

     

       110
       110
       +
             <para>

     

       111
       111
       +
               Backups can be configured with the options in

     

       112
       112
       +
               <link linkend="opt-services.gitlab.backup.keepTime">services.gitlab.backup</link>.

     

       113
       113
       +
               Use the

     

       114
       114
       +
               <link linkend="opt-services.gitlab.backup.startAt">services.gitlab.backup.startAt</link>

     

       115
       115
       +
               option to configure regular backups.

     

       116
       116
       +
             </para>

     

       117
       117
       +
             <para>

     

       118
       118
       +
               To run a manual backup, start the

     

       119
       119
       +
               <literal>gitlab-backup</literal> service:

     

       120
       120
       +
             </para>

     

       121
       121
       +
             <programlisting>

     

       122
       122
       +
       $ systemctl start gitlab-backup.service

     

       123
       123
       +
       </programlisting>

     

       124
       124
       +
           </section>

     

       125
       125
       +
           <section xml:id="module-services-gitlab-maintenance-rake">

     

       126
       126
       +
             <title>Rake tasks</title>

     

       127
       127
       +
             <para>

     

       128
       128
       +
               You can run GitLab's rake tasks with

     

       129
       129
       +
               <literal>gitlab-rake</literal> which will be available on the

     

       130
       130
       +
               system when GitLab is enabled. You will have to run the command

     

       131
       131
       +
               as the user that you configured to run GitLab with.

     

       132
       132
       +
             </para>

     

       133
       133
       +
             <para>

     

       134
       134
       +
               A list of all available rake tasks can be obtained by running:

     

       135
       135
       +
             </para>

     

       136
       136
       +
             <programlisting>

     

       137
       137
       +
       $ sudo -u git -H gitlab-rake -T

     

       138
       138
       +
       </programlisting>

     

       139
       139
       +
           </section>

     

       149
       140
        
         </section>

     

       150
       150
       -
        </section>

     

       151
       141
        
       </chapter>