In this migration guide, web developer Dominik describes different challenges and stumbling blocks when migrating the version of the management tool “GitLab”. In the example shown, version 10.0.2 is migrated from a web server with VM Debian v7 to a current Debian v10 on-premises system. The use of Docker simplifies the installation process. We hope that this step-by-step guide will help everyone who is migrating or upgrading GitLab.

First: what is GitLab?

In many software projects, the source code is not at the customer but in the custody of the service provider. The decentralized management tool “GIT” offers many advantages in terms of version management. The “GitLab” web application goes one step further: developers are supported with a web interface for user management. The tool also enables the integration of other services such as the “Easy Redmine” ticket system.
In this migration example, GitLab was deployed to a public web server about three years ago. To date: Without any kind of problematic incidents. GitLab is now to be migrated to an      on-premises system as part of a restructuring.

Forging challenges and stumbling blocks when planning
GitLab version 10.0.2. previously ran on a Debian v7 server and is now to be migrated to a current Debian v10. A plan has been quickly drawn up for this.

The plan:
1. Create and extract backup on old server.
2. Install a new GitLab on a new server.
3. Import backup to new server.
Finished!
Not quite …

“You can only restore a backup to exactly the same version and type (CE / EE) of GitLab on which it was created.” Quelle: GitLab,  https://docs.gitlab.com/ee/raketasks/backup_restore.html (2020)

1. So we need exactly the same version of GitLab on the new server as on the old one. A new plan quickly began.The new plan:
   1. Create and extract backup on old server.
   2. Install the old GitLab on a new server.
   3. Import backup to new server.
   4. Upgrade GitLab to the current version.
   Finished!

In its installation instructions, GitLab itself recommends that the installation is to be carried out using “Omnibus“. Omnibus installs all required programs, such as “PostgreSQL”, “Redis” and “Unicorn”.

When looking for the old packages, it turned out that there is no „Omnibus“ support for the GitLab version that we are using. So, shall we install everything manually instead? There is an alternative though: Docker.

Why Docker? Why not….

Docker is a software that creates an isolated environment through container virtualization. Only the resources required are available for a program. In our case, a GitLab container holds all the necessary programs and tools.

A great advantage of this isolation is that you can easily remove a container without leaving any data garbage in case it does not work properly. In this example, we use Docker analog to Omnibus. True to the motto: We have it all covered.
In the “DockerHub” there is even an old container package for the version GitLab 10.0.2 – YES!
A new improved plan is all that is needed right now.

The improved new plan:
1. Create and extract backup on the old server.
2. Install Docker and GitLab Container.
3. Import the backup on the new server.
4. Upgrade GitLab to the current version.

OK, that is the plan is. Let’s start!

Implementation & Linux shell commands

The necessary steps and the corresponding Linux shell commands are described below:
1. Create and extract backup on the old server:
By default, GitLab stores backups under “/ var / opt / gitlab / backups”. The backup that will be created shortly can be extracted from there.

Extract now. In our case, I copied the “Backup .tar file” into the FTP download area and downloaded it from there. Alternatively, you could also use SCP:

2. Install Docker & GitLab Container
First we install Docker in Debian. It must be ensured that the hardware requirements are met.

Next we install the older GitLab container 10.0.2-ee.0.

To the –volume:
GitLab stores various settings, logs and backups distributed in various Linux file directories (/ etc, var / log, / var / opt). we mount the three directories to / home / gitlab / *, so that we can work with this data outside the container and it is persistent.

Another look to see if the GitLab user interface is accessible:

Perfect! We are ready for step number 3 from our plan.

3. Import the backup to the new server
First of all we need the backup file on the new server. In this case I use SFTP and copy the backup into the home directory. Alternatively, you could use SCP.

GitLab takes one to two minutes to restart. If we now check the GitLab web interface, we can see that the backup has successfully imported all the data again. Even the logo of our “SampleMe” example can be seen again at the top of the picture :)

4. Upgrade GitLab to the current version
   Now, quickly upgrade GitLab from 10.0.2 to the current version (12.9.) And … CRASH!
   Unfortunately, I had the painful experience that a direct jump from GitLab 10 to 12 is not possible.

   “It is considered safe to jump between patch versions and minor versions within one major version.”
   Source: GitLab, https://docs.gitlab.com/ee/policy/maintenance.html#version-12-onwards-extra-step-for-major-upgrades (2020)

a step-by-step upgrade is necessary here: 10.0.2 => 11.0.0 => 11.11.0 => 12.0.0 => latest (12.9.2)
The following steps must therefore be repeated for each CONTAINER VERSION:
• 11.0.0-ee.0
• 11.11.0-ee.0
• 12.0.0-ee.0
• 12.9.1-ee.0
• latest

Conclusion

Cool, so now we have migrated GitLab version 10.0.2 from server A to server B and upgraded GitLab to the current status. There were some hurdles, but there was always a solution. The possibility of using Docker made the job much easier.
But one thing should be remembered: Upgrading with two major jumps can be prevented simply by performing regular updates.

I hope that this guide will help others. I would like to wish everyone success facing this challenge.

Best regards,
Dominik