GitLab

USE flags

U I
- - favicon       : For the Custom Favicon to work, GraphicsMagick needs to be installed
- - gitlab-config : Config in /opt/gitlab/gitlab/config istead of /etc/gitlab (s. news 2021-02-22-etc-gitlab)
- - gitaly_git    : Use the Git version provided by Gitaly 
- - mail_room     : Enables support for GitLab MailRoom 
+ + puma          : Enables support for the puma HTTP server 
- - unicorn       : Enables support for the unicorn HTTP server
+ + systemd       : Enable use of systemd-specific libraries and features like socket activation or session tracking

The gitaly-config USE flag is explained in the 2021-02-22-etc-gitlab news of the overlay. The gitaly_git USE flag uses the bundled Git from gitlab-gitaly instead of dev-vcs/git. The puma USE flag is preselected because with GitLab 12.9 Puma has replaced Unicorn as the default web server. The systemd USE flag is preselected since the maintainer of the overlay ran out of OpenRC hosts for init script testing. :-) But with the help of some users of the overlay the OpenRC init scripts will be provided further on.

Preparations

Add the following keywords to be accepted by Portage (we use amd64 as architecture here; x86 is also available):

www-apps/gitlab ~amd64
dev-vcs/gitlab-shell ~amd64
www-servers/gitlab-workhorse ~amd64

From GitLab 13.6 on Ruby 2.7 or later is required. Until Ruby 2.7 will be stabilized one must add further keywords to be accepted. As of January 2021 these were the following versions:

=dev-lang/ruby-2.7.2 ~amd64
=dev-ruby/minitest-5.13.0 ~amd64
=dev-ruby/net-telnet-0.2.0 ~amd64
=dev-ruby/power_assert-1.1.7 ~amd64
=dev-ruby/rake-13.0.1 ~amd64
=dev-ruby/xmlrpc-0.3.0 ~amd64
=dev-ruby/rdoc-6.2.0 ~amd64
=dev-ruby/kpeg-1.1.0-r1 ~amd64
=virtual/rubygems-16 ~amd64
=dev-ruby/rubygems-3.1.4 ~amd64

The overlay overrides the gentoo acct-user/git package introducing a new USE flag gitlab which creates the git user as required by www-apps/gitlab with HOME in /var/lib/gitlab/ and as member in the redis group. Add the USE Flag:

Emerge

Next emerge the package and follow the instructions given on the output (here the output of a 13.8.4 installation for an example).

...
* For this new installation, proceed with the following steps:
*
*   1. Create a database user for GitLab.
*      On your database server (local ore remote) become user postgres:
*        su -l postgres
*      GitLab needs two PostgreSQL extensions: pg_trgm and btree_gist.
*      To create the extensions if they are missing do:
*        psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
*        psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS btree_gist;"
*      Create the database user:
*        psql -c "CREATE USER gitlab CREATEDB PASSWORD 'gitlab'"
*      Note: You should change your password to something more random ...
*      You may need to add configs for the new 'gitlab' user to the
*      pg_hba.conf and pg_ident.conf files of your database server.
*
*   2. Edit /etc/gitlab/database.yml in order to configure
*      database settings for "production" environment.
*
*   3. Edit /etc/gitlab/gitlab.yml
*      in order to configure your GitLab settings.
*
*      GitLab expects the parent directory of the config files to
*      be its base directory, so you have to sync changes made in
*      /etc/gitlab/ back to /opt/gitlab/gitlab/config/ by running
*        rsync -aHAX /etc/gitlab/ /opt/gitlab/gitlab/config/
*
*   4. You need to configure redis to have a UNIX socket and you may
*      adjust the maxmemory settings. Change /etc/redis.conf to
*        unixsocket /var/run/redis/redis.sock
*        unixsocketperm 770
*        maxmemory 1024MB
*        maxmemory-policy volatile-lru
*
*   5. Gitaly must be running for the "emerge --config". Execute
*          systemctl --job-mode=ignore-dependencies start gitlab-gitaly.service
*      Make sure the Redis server is running and execute:
*          emerge --config "=www-apps/gitlab-13.8.4"

Work through the list. Note that the database you specify in /etc/gitlab/database.yml will be deleted by the "Initializing database" step below! Finally run the configuration script (again with an example output).

...
Configuring pkg...
* Checking configuration files ...
* Hit <Enter> to continue
* Set the Administrator/root password:  *
* Set the Administrator/root email: gitlab@theomail.informatik.uni-stuttgart.de
* Initializing database ...
This will create the necessary database tables and seed the database.
You will lose any previous data stored in the database.
Do you want to continue (yes/no)? yes
... (messages from the database creation and initialization)
*
* Now start gitlab with
* $ systemctl start gitlab.target
*
* You might want to check your application status. Run this:
* $ cd /opt/gitlab/gitlab
* $ sudo -u git ruby /usr/bin/bundle exec rake gitlab:check RAILS_ENV=production
*
* GitLab is prepared now.
* To configure your nginx site have a look at the examples configurations
* in the /opt/gitlab/gitlab/lib/support/nginx/ folder.

The Administrator password and email are used for the initial administrator account of the GitLab web application. In the above omitted "messages from the database creation and initialization" you'll find the login and password for this account. You should use a working email address as on startup GitLab will send an "Access to the GitLab Instance group was granted" mail to this address.

Now start GitLab, log in with the administrator account and adopt the default settings to your need.

Files

GitLab expects the parent directory of the config files to be its base directory, so the config has to stay in /opt/gitlab/gitlab/config/. Symlinking /opt/gitlab/gitlab/config -> /etc/gitlab doesn't work as GitLab uses the real path of the config files to get the parent directory. In order to use the standard Gentoo way of managing config files, the config files are copied to /etc/gitlab/ where you edit them and then synced back to /opt/gitlab/gitlab/config/ by running:

This rsync command is run automatically on start/restart of Gitlab. Only before the emerge --config of the first installation you have run this manually as GitLab does not run then but the emerge --config needs the up-to-date config. The rsync command updates only those config files in /opt/gitlab/gitlab/config/ that exist in /etc/gitlab/, so it suffices to have only the changed ones in /etc/gitlab/.

When the gitlab-config USE flag is set /etc/gitlab/ isn't used and you'll have to edit the files in /opt/gitlab/gitlab/config/ directly.

Service

Diagnostics

Run this command to get a full diagnostic.