GitLab
The Gitlab overlay, originally the CVUT overlay, is currently on par with the latest GitLab version (15.9.0 as of Februar 2023). The repo and issues can be found here.
With version 13.8.3 the former www-apps/gitlabhq package was renamed to www-apps/gitlab. Since the gitlab core and gitlab-gitaly must neccessarily have the same version the former dev-vcs/gitlab-gitaly package was abandoned and gitlab-gitaly is now included in the www-apps/gitlab package.
By means of "Post Deployment Migrations" as described here starting with version 13.8.4 upgrading takes place without downtime (Nearly: The still required restart needs some time). This made the slots obsolete and so the upgrade procedure less complicated.
The migration from a www-apps/gitlabhq installation to a www-apps/gitlab one is supported by all www-apps/gitlab-13.8.x ebuilds. For more information read the 2021-02-10-gitlabhq-to-gitlab news message of the overlay.
Installation
The gitlab ebuild repository must first be configured to be used by Portage. It can be added manually, but is more easily configured using eselect repository (this may need to be installed, see preceding article).
To add using eselect repository:
root #eselect repository enable gitlab
root #emerge --sync gitlab
GitLab requires the use of a database backend. Since version 12 PostgreSQL is the only supported database.
USE flags
U I - - favicon : For the Custom Favicon to work, GraphicsMagick needs to be installed + + gitaly_git : Use the Git version provided by Gitaly - - gitlab-config : Config in /opt/gitlab/gitlab/config instead of /etc/gitlab (s. news 2021-02-22-etc-gitlab) - - kerberos : Add kerberos support - - mail_room : Enables support for GitLab MailRoom - - pages : Pulls in the compatible version of www-apps/gitlab-pages - - prometheus : Enables support for the Prometheus monitoring system - - relative_url : Support for relative url + + 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 (since version 13.11.4 its default changed to 'on', as recommended by upstream). The gitaly_git USE flag uses the bundled Git from gitlab-gitaly instead of dev-vcs/git. The former puma and unicorn USE flags were removed because with GitLab 14.0 Unicorn was removed by upstream and Puma is now the only supported 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):
root #nano /etc/portage/package.accept_keywords/gitlabwww-apps/gitlab ~amd64 dev-vcs/gitlab-shell ~amd64
If you disable the gitaly-git USE flag you also have to keyword the required version of dev-vcs/git (>= 2.38.0 as of gitlab version 15.9.0) and unmask its pcre-jit USE flag:
root #nano /etc/portage/profile/package.use.maskFrom GitLab 13.6 on Ruby 2.7 or later is required.
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:
root #echo "acct-user/git gitlab" >> /etc/portage/package.use/gitlabEmerge
Next emerge the package and follow the instructions given on the output (here the output of a 14.5.0 installation with systemd USE flag for an example).
root #emerge -av gitlab... * 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 three PostgreSQL extensions: pg_trgm, btree_gist, plpgsql. * 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;" * psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS plpgsql;" * 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. * This ebuild assumes that you run the Postgres server on a * different machine. If you run it here add the dependency * systemctl edit gitlab-puma.service * In the editor that opens, add the following and save the file: * [Unit] * Wants=postgresql.service * After=postgresql.service * * systemctl edit gitlab-sidekiq.service * In the editor that opens, add the following and save the file: * [Unit] * Wants=postgresql.service * After=postgresql.service * * 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. * * With gitaly_git USE flag enabled the included git was installed to * /opt/gitlab/gitlab-gitaly/bin/. In order to use it one has to set the * [git] "bin_path" variable in "/etc/gitlab-gitaly/config.toml" and in * "/etc/gitlab/gitlab.yml" to "/opt/gitlab/gitlab-gitaly/bin/git" * * 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 * This is done automatically on start/restart of gitlab * but sometimes it is neccessary to do it manually by * 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 * Supervise Redis with systemd: Change /etc/redis/redis.conf to * daemonize no * supervised systemd * #pidfile /run/redis/redis.pid * Make matching changes to the systemd unit file: * Create /etc/systemd/system/redis.service.d/10fix_type.conf * and insert the following lines * [Service] * Type=notify * PIDFile= * Then run * systemctl daemon-reload * systemctl restart redis.service * * 5. Gitaly must be running for the "emerge --config". Execute * systemctl start gitlab-update-config.service * systemctl --job-mode=ignore-dependencies start gitlab-gitaly.service * Make sure the Redis server is running and execute: * emerge --config "=www-apps/gitlab-15.9.0"
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).
root #emerge --config "=www-apps/gitlab-15.9.0"... Configuring pkg... * Checking configuration files ... * Set the Administrator/root password: ********* * Set the Administrator/root email: gitlab@<your-domain> * 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 copy the nginx example configs you need, at least gitlab-ssl, (plus gitlab-pages-ssl if you use pages) from /opt/gitlab/gitlab/lib/support/nginx/ to /etc/nginx/sites/ and adopt them to your setup.
Finally start Nginx and GitLab, log in with the administrator account and adopt the default settings to your need.
Configuration
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 we edit them and then synced back to /opt/gitlab/gitlab/config/ by running:
root #rsync -aHAX /etc/gitlab/ /opt/gitlab/gitlab/config/Note that the trailing slashes are important here!
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.
Web server
NGINX is the officially supported web server for GitLab. If you cannot or do not want to use NGINX as theweb server, see GitLab recipes. You have to set up a sites config for GitLab. See /opt/gitlab/gitlab/lib/support/nginx/gitlab-ssl for an example site configuration.
The web interface is available at the URL you configured in /etc/gitlab/gitlab.yml:
## GitLab settings
gitlab:
## Web server settings (note: host is the FQDN, do not include http://)
host: gitlab.<your-domain>
port: 443 # Set to 443 if using HTTPS, see installation.md#using-https for additional HTTPS configuration details
https: true # Set to true if using HTTPS, see installation.md#using-https for additional HTTPS configuration details
With the above the URL would be https://gitlab.<your-domain>.
Testing
Diagnostics
Run this command to get a full diagnostic.
git #cd /opt/gitlab/gitlabgit #bundle exec rake gitlab:env:info RAILS_ENV=production
git #bundle exec rake gitlab:check RAILS_ENV=production
Usage
Service
OpenRC
Starting gitlab:
root #rc-service gitlab startCurrent status:
root #rc-service gitlab statusStarting automatically at system boot:
root #rc-update add gitlab defaultsystemd
Starting gitlab:
root #systemctl start gitlab.targetCurrent status:
root #systemctl list-dependencies gitlab.targetStarting automatically at system boot:
root #systemctl enable gitlab.targetUpgrade
Upstream removed several deprecated features in the annual major release 14.0.0. It is strongly advised to work through the upstream website about "information about deprecation and removals for self-managed instances" at https://about.gitlab.com/releases/2021/05/22/gitlab-13-12-released/#release-deprecations before upgrading to version 14!
It should be especially pointed out that as announced in GitLab 13.0 legacy storage is deprecated and will be removed in GitLab 14.0. Before upgrading to GitLab 14.0 you must migrate fully to hashed storage!
The www-apps/gitlab ebuild will check if one is on a supported "Upgrade path" (see the upstream update doc/update/zero_downtime.md) to ensure that the requirements for "Upgrading without downtime" are met. The upgrade steps are:
root #emerge -u gitlab... * Migrating database without post deployment migrations ... * * Update the config in /etc/gitlab and then run * systemctl restart gitlab.target * * To complete the upgrade of your GitLab instance, run: * emerge --config "=www-apps/gitlab-15.9.0" * * * Note: With gitaly_git USE flag enabled the included git was installed to * /opt/gitlab/gitlab-gitaly/bin/. In order to use it one has to set the * [git] "bin_path" variable in "/etc/gitlab-gitaly/config.toml" and in * "/etc/gitlab/gitlab.yml" to "/opt/gitlab/gitlab-gitaly/bin/git"
If there are config updates (there were none in the above example output), do an etc-update before the restart:
root #etc-updateroot #systemctl daemon-reloadroot #systemctl restart gitlab.targetThen do the database migrations with post deployment migrations by executing:
root #emerge --config "=www-apps/gitlab-15.9.0"Configuring pkg...
* Migrating database ... * Clean up cache ... * Configure Git to enable packfile bitmaps ... * * 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. * Ensure you're still up-to-date with the latest NGINX configuration changes: * $ cd /opt/gitlab/gitlab * $ git -P diff v15.8.3:lib/support/nginx/ v15.9.0:lib/support/nginx/
If the git -P diff ... command shows any differences in the nginx config examples you should merge the updates into your nginx config and restart nginx.
Backup
You should do a regular (daily) backup of the database. Besides the backup of the database server it's also recommended to do a backup with the GitLab backup tool:
git #cd /opt/gitlab/gitlabgit #bundle exec rake gitlab:backup:create RAILS_ENV=productionThis creates a complete GitLab-Backup (see the GitLab-Docs for what's included) to the backup path configured in /etc/gitlab/gitlab.yml. Just create a systemd timer or cron job to run this e. g. daily.
External Resources
- ArchWiki GitLab - can be helpful while configuration section is incomplete in Gentoo wiki.
- Official documentation
- Configuration files Documentation