Migrate GitLab from CentOS to Ubuntu on ECS

In this post, we will migrate GitLab from CentOS 7.9 to Ubuntu 20.04 LTS on Alibaba Cloud ECS (Elastic Compute Service), as CentOS is EOL and Ubuntu is more popular.

Check GitLab Version

As restore GitLab backup requires the same version of GitLab, we need to check current GitLab version.

You can only restore a backup to exactly the same version and type (CE/EE) of GitLab on which it was created (for example CE 15.1.4).

See Restore GitLab | GitLab.

$ cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
15.9.0-ee

Here we have GitLab 15.9 Enterprise Edition installed, and on new server we will also install this version.

Backup GitLab

By default, our GitLab Backup package is located at /var/opt/gitlab/backups/, this could be checked by cat /etc/gitlab/gitlab.rb | grep backup.

gitlab-rake gitlab:backup:create

This command will automatically pack up all non-sensitive GitLab data, including repositories, database, configuration, etc. The backup package will be located at the directory mentioned before, with name such as 1690438526_2023_07_27_15.9.0-ee_gitlab_backup.tar.

The file name contains the UNIX timestamp and GitLab version.

$ date -d @1690438526
Thu Jul 27 14:15:26 CST 2023

Additionally, we also need to pack up some sensitive data, gitlab.rb and gitlab-secrets.json, which are all located at /etc/gitlab/.

sudo tar cvf gitlab-secrets.tar /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json

This will create a tar file gitlab-secrets.tar in current directory.

Now we have all data needed to restore GitLab on new server. Here we only have one cloud server, so we simply download the backup packages via FTP to our local machine. It can also be transferred to new server via scp, secure copy.

Install GitLab on Ubuntu

Simply follow the GitLab official installation guide on Ubuntu, but only first few steps. See Download and install GitLab | GitLab.

sudo apt update
sudo apt install -y curl openssh-server ca-certificates tzdata perl
sudo apt install -y postfix
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash
sudo EXTERNAL_URL="121.XXX.XXX.XXX" apt install gitlab-ee=15.9.0-ee.0

Note that we specify the GitLab version to install, the version is just the same as the GitLab Docker image tag, which is 15.9.0-ee.0 here.

The EXTERNAL_URL is the public IP address or domain name of the server, which is used to access GitLab.

Also, remember to select Internet Site for postfix configuration, with value same as EXTERNAL_URL as the system mail name.

And now when we access to EXTERNAL_URL, we will see the GitLab login page.

Restore GitLab

Stop GitLab Service

Stop services that will read / write to database, such as sidekiq and puma, and we can check its status by gitlab-ctl status.

gitlab-ctl stop sidekiq
gitlab-ctl stop puma
gitlab-ctl status

New version of GitLab migrates from unicorn to puma, so there is no need to stop unicorn service any more.

Place Backup Files

We need to upload our backup packages to new server, and organize them correctly.

Here we also use FTP to upload files from our local machine.

The [TIMESTAMP]_gitlab_backup.tar should be placed at /var/opt/gitlab/backups/ as before, and gitlab.rb and gitlab-secrets.json extracted from gitlab-secrets.tar should be placed at /etc/gitlab/, replacing the original files.

Restore the Backup

cd /var/opt/gitlab/backups/
gitlab-rake gitlab:backup:restore BACKUP=1690438526_2023_07_27_15.9.0-ee

The BACKUP parameter is the file name of backup package, without _gitlab_backup.tar suffix.

Restart GitLab Service

Restart the services we stopped before and check their status.

gitlab-ctl start
gitlab-ctl status
gitlab-rake gitlab:check SANITIZE=true

Now all services should be running, and we can access to GitLab just as before, with all user data and repositories are restored.

References

1. Back up and restore GitLab | GitLab
2. Download and install GitLab | GitLab
3. Installing Older Versions of Gitlab on Ununtu - How to Use GitLab - GitLab Forum
4. 部署和使用GitLab
5. Gitlab备份和恢复操作记录-阿里云开发者社区
6. Elastic Compute Service (ECS): Elastic & Secure Cloud Servers - Alibaba Cloud
7. 云服务器ECS_云主机_服务器托管_弹性计算-阿里云
8. About/Product - CentOS Wiki
9. How we migrated application servers from Unicorn to Puma | GitLab