/ HowTos

Migrating GitLab to GitLab-Omnibus

I've recently discovered that the great people at GitLab have released the GitLab-Omnibus.

This project creates full-stack platform-specific downloadable packages for GitLab.

This is great, especially since a manual install on a Red Hat system can be a bit of a pain to maintain.

Use this doc at your own risk! (it's always good to test these things somewhere safe. Might I suggest in a Vagrant??)

Coming from a Manual Install (MySQL)

Some assumptions

  • You are coming from a manual GitLab installation that uses MySQL.
  • You know how to manually upgrade this existing install.
  • You've already installed the RPM or DEB version of GitLab on your new server
  • Your local workstation has python2.7 installed

Some notes

  • If you have any extra customization (branding and such) this will not transfer
  • If you are using LDAP, these settings will not transfer. You will have to add them again to the new install. (Make sure you are looking at the correct version of this doc. At the time of writing, I was working with 6.8)

On your Existing Installation

First thing you are going to want to do is get your manual install completely up-to-date (or at least to one of the versions available from the omnibus archives) as you can't restore across versions of GitLab. I'm going to assume you have done this already.

Next, we need to backup our exiting installation.

## Run as your gitlab user inside the install directory
## example: /home/git/gitlab/

bundle exec rake gitlab:backup:create RAILS_ENV=production

Now, dump the existing database like so. In this example, we are calling the dumped content current_install.mysql which is being dumped from our production database gitlabhq_production.

## You will need your MySQL adim password for this

mysqldump --compatible=postgresql --default-character-set=utf8 -r current_install.mysql -u root gitlabhq_production -p

Make sure the backup archive and database dump are in a place you can get to from your local workstation.

## Example: moving our backup from gitlab and our mysql database dump to a your user's home folder

cp /home/git/gitlab/tmp/1234567890_gitlab_backup.tar /home/your_user/

cp /path/to/current_install.mysql /home/your_user/

On your Local Workstation

Pull down the backup archive and the database dump file.

scp your_user@existing.install.com:1234567890_gitlab_backup.tar .

scp your_user@existing.install.com:current_install.mysql .

Extract the archive. You'll want to do this in an empty directory. After it is extracted, you may delete the archive. (Be sure to write down the name of this file though, you will need it later)

mkdir ~/tar_me_from_inside && cd ~/tar_me_from_inside
tar -xvf ~/1234567890_gitlab_backup.tar
rm ~/1234567890_gitlab_backup.tar

Clone down this project.
Clone down this other project. It has been pointed out to me in the comments by 'TheDude' that there is fork specifically for GitLab databases. Fair warning, I've not had time to test this version of the conversion script, but it is within gitlabhq's GitHub pages, so it's probably good ;)

cd ~/
git clone -b gitlab https://github.com/gitlabhq/mysql-postgresql-converter.git

Convert the database dump file from the original install to the new install compatible psql file. You will need Python 2.7 for this.

cd ~/mysql-postgresql-converter
python db_converter.py ~/current_install.mysql ~/database.psql

Remove the db/database.sql from your extracted backup and move the new one in its place. (Using the same name as the one you just deleted)

cd ~/tar_me_from_inside
rm db/database.sql
mv ~/database.psql db/database.sql

Now, tar up this directory, naming it the same as the original backup archive file.

cd ~/tar_me_from_inside && tar -zcvf ~/1234567890_gitlab_backup.tar . && cd ~/

Finally, place the new backup archive on your new install server.

scp ~/1234567890_gitlab_backup.tar your_user@new.server.com:.

On your New RPM/DEB Install

Move the backup to /var/opt/gitlab/backups

mv ~/1234567890_gitlab_backup.tar /var/opt/gitlab/backups

Stop unicorn and sidekiq, then run the restore.

## Run this with sudo or as root

gitlab-ctl stop unicorn
gitlab-ctl stop sidekiq
gitlab-rake gitlab:backup:restore BACKUP=1234567890

If all went well, you should be able to start GitLab back up, log in, and find all your projects just as you left them!!

gitlab-ctl start