Migrating Gitlab from source installation to Omnibus

• 4 minutes read
#gitlab   #tools

I use Gitlab at work since 2012 and we are very happy with it. Gitlab is designed with developers in mind, providing the features and integrations to build great solutions from idea to production.

However, our Gitlab instance was an old setup configured from source and updated monthly by following a well documented but tedious manual process.

Last year we decided to move to a more modern Gitlab setup, called Omnibus. Omnibus GitLab is a way to package different services and tools required to run GitLab, so that most users can install and update it without a laborious configuration. This post describes all the steps to migrate our old instance to a new Omnibus Gitlab server instance.

Step 1: Migrate your current instance to the newest Gitlab version

In order to avoid version conflicts, I recommend you to update your current instance to the latest Gitlab version. Thus, follow these instructions before proceeding to the next steps.

Step 2: Migrate MySql to Postgres

If your current instance uses Mysql as database, then you will need to move your data to Postgres, because Omnibus Gitlab only supports this database. In fact, starting from GitLab 12.1, only PostgreSQL is supported. Therefore, migrate your database to Postgres if you are using MySql.

Note: Gitlab’s official docs inform you need at least PostgreSQL 9.2, however Gitlab uses jsonb then you need to install PostgreSQL 9.4 or greater.

Step 3: Create a new server and install GitLab Omnibus

Create a new server using a Linux distro of your choice and install GitLab Omnibus. GitLab Omnibus is installed under /var/opt/gitlab directory.

Step 4: Create a backup from your current server and restore it in the new one

In GitLab source installation, you can create a backup executing the following command from gitlab’s directory:

sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production

Copy the backup file to the directory /var/opt/gitlab/backups/ of the new server. Then restore it in your new installation by running:

gitlab-rake gitlab:backup:restore RAILS_ENV=production

This takes some time, have a coffee!

Step 5: Configure the new server

Your new Gitlab’s server is almost complete, you need to configure your new installation. All GitLab’s configuration files are placed inside /etc/gitlab.

Editing the file /etc/gitlab/gitlab.rb, search for the following settings and customize them according to your needs.

All these configurations already exist in your current installation, check the file /home/git/gitlab/config/gitlab.yml and copy accordingly. If you use more custom configurations in your current instance (like LDAP, GitLab Pages, …), then copy these configurations to your new server as well.

Also, is strongly recommended to configure SSL in your server.

To finalize the configuration process, you need to copy the secrets from your current installation to the new one. GitLab uses secrets to multiple purposes, like database encryption, session encryption, etc. Then, you will need to restore these secrets to make your new instance run perfectly.

In GitLab Omnibus all secrets are placed in a single file /etc/gitlab/gitlab-secrets.json. But in Gitlab installed from source, the secrets are placed in multiple files.

First you need to restore secrets related to Rails. Copy the values of db_key_base, secret_key_base and otp_key_base from /home/git/gitlab/config/secrets.yml (Gitlab source) to the equivalent ones in /etc/gitlab/gitlab-secrets.json (Gitlab Omnibus).

Then, copy the content of the file /home/git/gitlab-shell/.gitlab_shell_secret (Gitlab source) to Gitlab Shell’s secret_token in /etc/gitlab/gitlab-secrets.json (Gitlab Omnibus).

The /etc/gitlab/gitlab-secrets.json file is something like:

{
  "gitlab_workhorse": {
    "secret_token": "..."
  },
  "gitlab_shell": {
    "secret_token": "..."
  },
  "gitlab_rails": {
    "secret_key_base": "...",
    "db_key_base": "...",
    "otp_key_base": "...",
  }
  ...
}

If you use Gitlab Pages, Registry or Mattermost, you will also need to copy secrets from your current installation to the new one.

To apply your configuration changes to your new server execute the command:

gitlab-ctl reconfigure

You made it! Your new server is ready to use and future updates will be simpler to apply!