This article explains how to set up a self hosted GitLab instance.
The Gitlab overlay, originally the CVUT overlay, is currently on par with the latest GitLab version (16.6.0 as of November 2023). The repo and issues can be found here.
With version 13.8.3 the former gitlab core and gitlab-gitaly must necessarily have the same version the former package was abandoned and gitlab-gitaly is now included in the package.package was renamed to . Since the
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/gitlab-13.8.x ebuilds.installation to a one is supported by all
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:
eselect repository enable gitlab
emaint sync -r gitlab
GitLab requires the use of a database backend. Since version 12 PostgreSQL is the only supported database.
- - 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
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 . The former
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.
Add the following keywords to be accepted by Portage (we use amd64 as architecture here; x86 is also available):
The overlay overrides the gentoo
gitlab which creates the git user as required by with HOME in /var/lib/gitlab/ and as member in the redis group. Add the USE Flag:
echo "acct-user/git gitlab" >> /etc/portage/package.use/gitlab
After emerging the package the ebuild will give detailed instructions for the initial setup. This will cover:
- Creating and preparing the Postres database
- Editing /etc/gitlab/database.yml in order to configure database settings for "production" environment
- Editing /etc/gitlab/gitlab.yml in order to configure the GitLab settings
- Configuring and restarting redis
- Applying config changes and starting Gitaly
- Finally running emerge --config
Note that the database specified in /etc/gitlab/database.yml will be deleted by the Initializing database step of emerge --config!
Also the emerge --config will ask for password and email of the initial administrator account of the GitLab web application. It should be a working email address as on startup GitLab will send an Access to the GitLab Instance group was grante mail to this address.
Now copy one of the nginx example configs, at least gitlab-ssl, (plus gitlab-pages-ssl if pages is used) from /opt/gitlab/gitlab/lib/support/nginx/ to /etc/nginx/sites/ and adopt them as needed.
Finally start Nginx and GitLab, log in with the administrator account and check/adopt the default settings.
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 they are edited and then synced back to /opt/gitlab/gitlab/config/ each time the service is (re)started or by running:
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 this has to be run manually as GitLab was'n started yet 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/.
gitlab-config USE flag is set /etc/gitlab/ isn't used and the config files must be edited in /opt/gitlab/gitlab/config/ directly.
NGINX is the officially supported web server for GitLab. See opt/gitlab/gitlab/lib/support/nginx/gitlab-ssl for an example site configuration. For using a different web server, see GitLab recipes.
The web interface is available at the URL configured here:
## GitLab settings
## Web server settings (note: host is the FQDN, do not include http://)
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.<sample-domain>.
Run this command as user git to get a full diagnostic.
bundle exec rake gitlab:env:info RAILS_ENV=production
bundle exec rake gitlab:check RAILS_ENV=production
rc-service gitlab start
rc-service gitlab status
Starting automatically at system boot:
rc-update add gitlab default
systemctl start gitlab.target
systemctl list-dependencies gitlab.target
Starting automatically at system boot:
systemctl enable gitlab.target
The www-apps/gitlab ebuild will check if one is on a supported "Upgrade path" (see the upstream update doc/update/index.md#upgrade-paths) to ensure that the requirements for "Upgrading without downtime" are met. The upgrade steps are:
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 this GitLab instance, run: * emerge --config "=www-apps/gitlab-16.6.0" * * * Note: With gitaly_git USE flag enabled the included git was installed to * /opt/gitlab/gitlab-gitaly/bin/. In order to use it 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:
systemctl restart gitlab.target
Then do the database migrations with post deployment migrations by executing:
emerge --config "=www-apps/gitlab-16.6.0"
* Migrating database ... * Clean up cache ... * * To check the 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 beeing still up-to-date with the latest NGINX configuration changes: * $ cd /opt/gitlab/gitlab * $ git -P diff v16.5.2:lib/support/nginx/ v16.6.0:lib/support/nginx/
Besides the regular (daily) backup of the database server it's also recommended to do a backup with the GitLab backup tool:
bundle exec rake gitlab:backup:create RAILS_ENV=production
This 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.