Skip to content
Snippets Groups Projects
Commit 39809227 authored by Marin Jankovski's avatar Marin Jankovski
Browse files

Merge branch 'ci-migration-doc-improvements' into 'master' 

Ci migration doc improvements

Use export improvements in CI 8.0.1, make upgrades a more prominent part of the process, do not shut down GitLab during CI data import.

See merge request !1387
parents 0ce5fb71 d2ab95d1
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/migrate_ci_to_ce/README.md
+ 173
− 172
View file @ 39809227
@@ -5,232 +5,243 @@ Edition (EE), GitLab CI is no longer its own application, but is instead built
into the CE and EE applications.
 
This guide will detail the process of migrating your CI installation and data
into your GitLab CE or EE installation.
into your GitLab CE or EE installation. **You can only migrate CI data from
GitLab CI 8.0 to GitLab 8.0; migrating between other versions (e.g.7.14 to 8.1)
is not possible.**
 
### Before we begin
We recommend that you read through the entire migration process in this
document before beginning.
 
**You need to have a working installation of GitLab CI version 8.0 to perform
this migration. The older versions are not supported and will most likely break
this migration procedure.**
### Overview
 
This migration cannot be performed online and takes a significant amount of
time. Make sure to plan ahead.
In this document we assume you have a GitLab server and a GitLab CI server. It
does not matter if these are the same machine.
 
If you are running a version of GitLab CI prior to 8.0 please follow the
appropriate [update guide](https://gitlab.com/gitlab-org/gitlab-ci/tree/master/doc/update/)
before proceeding.
The migration consists of three parts: updating GitLab and GitLab CI, moving
data, and redirecting traffic.
 
The migration is divided into four parts and covers both manual and Omnibus
installations:
Please note that CI builds triggered on your GitLab server in the time between
updating to 8.0 and finishing the migration will be lost. Your GitLab server
can be online for most of the procedure; the only GitLab downtime (if any) is
during the upgrade to 8.0. Your CI service will be offline from the moment you
upgrade to 8.0 until you finish the migration procedure.
 
1. [GitLab CI](#part-i-gitlab-ci)
1. [Gitlab CE (or EE)](#part-ii-gitlab-ce-or-ee)
1. [Nginx configuration](#part-iii-nginx-configuration)
1. [Finishing Up](#part-iv-finishing-up)
### Before upgrading
 
### Part I: GitLab CI
#### 1. Verify that backups work
 
#### 1. Stop GitLab CI
Make sure that the backup script on both servers can connect to the database.
 
# Manual installation
sudo service gitlab_ci stop
# Omnibus installation
sudo gitlab-ctl stop ci-unicorn ci-sidekiq
#### 2. Create a backup
The migration procedure modifies the structure of the CI database. If something
goes wrong, you will not be able to revert to a previous version without a
backup.
If your GitLab CI installation uses **MySQL** and your GitLab CE (or EE)
installation uses **PostgreSQL** you'll need to convert the CI database by
setting a `MYSQL_TO_POSTGRESQL` flag.
If you use the Omnibus package you most likely use **PostgreSQL** on both GitLab
CE (or EE) and CI.
You can check which database each install is using by viewing their
database configuration files:
cat /home/gitlab_ci/gitlab-ci/config/database.yml
cat /home/git/gitlab/config/database.yml
- If both applications use the same database `adapter`, create the backup with
this command:
# Manual installation
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production
```
# On your CI server:
# Omnibus
sudo gitlab-ci-rake backup:create
 
# Omnibus installation
sudo gitlab-ci-rake backup:create
# Source
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production
```
 
- If CI uses MySQL, and CE (or EE) uses PostgreSQL, create the backup with this
command (note the `MYSQL_TO_POSTGRESQL` flag):
Also check on your GitLab server.
 
# Manual installation
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production MYSQL_TO_POSTGRESQL=1
```
# On your GitLab server:
# Omnibus
sudo gitlab-rake gitlab:backup:create SKIP=repositories,uploads
 
# Omnibus installation
sudo gitlab-ci-rake backup:create MYSQL_TO_POSTGRESQL=1
# Source
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=repositories,uploads
```
 
#### 3. Remove cronjob
If this fails you need to fix it before upgrading to 8.0. Also see
https://about.gitlab.com/getting-help/
 
**Note:** This step is only required for **manual installations**. Omnibus users
can [skip to the next step](#part-ii-gitlab-ce-or-ee).
#### 2. Check source and target database types
 
# Manual installation
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec whenever --clear-crontab
Check what databases you use on your GitLab server and your CI server.
Look for the 'adapter:' line. If your CI server and your GitLab server use
the same database adapter no special care is needed. If your CI server uses
MySQL and your GitLab server uses PostgreSQL you need to pass a special option
during the 'Moving data' part. **If your CI server uses PostgreSQL and your
GitLab server uses MySQL you cannot migrate your CI data to GitLab 8.0.**
 
### Part II: GitLab CE (or EE)
```
# On your CI server:
# Omnibus
sudo gitlab-ci-rake env:info
 
#### 1. Ensure GitLab is updated
# Source
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec rake env:info RAILS_ENV=production
```
 
Your GitLab CE or EE installation **must be version 8.0**. If it's not, follow
the [update guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/7.14-to-8.0.md)
before proceeding.
```
# On your GitLab server:
# Omnibus
sudo gitlab-rake gitlab:env:info
 
If you use the Omnibus packages simply run `apt-get upgrade` to install the
latest version.
# Source
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
```
 
#### 2. Prevent CI usage during the migration process
#### 3. Storage planning
 
As an administrator, go to **Admin Area** -> **Settings**, and under **Continuous
Integration** uncheck **Disable to prevent CI usage until rake ci:migrate is run
(8.0 only)**.
Decide where to store CI build traces on GitLab server. GitLab CI uses
files on disk to store CI build traces. The default path for these build
traces is `/var/opt/gitlab/gitlab-ci/builds` (Omnibus) or
`/home/git/gitlab/builds` (Source). If you are storing your repository data in
a special location, or if you are using NFS, you should make sure that you
store build traces on the same storage as your Git repositories.
 
This will disable the CI integration and prevent users from creating CI projects
until the migration process is completed.
### I. Upgrading
 
#### 3. Stop GitLab
From this point on, GitLab CI will be unavailable for your end users.
 
Before you can migrate data you need to stop the GitLab service first:
#### 1. Upgrade GitLab to 8.0
 
# Manual installation
sudo service gitlab stop
First upgrade your GitLab server to version 8.0:
https://about.gitlab.com/update/
 
# Omnibus installation
sudo gitlab-ctl stop unicorn sidekiq
#### 2. Disable CI on the GitLab server during the migration
 
#### 4. Create a backup
After you update, go to the admin panel and temporarily disable CI. As
an administrator, go to **Admin Area** -> **Settings**, and under
**Continuous Integration** uncheck **Disable to prevent CI usage until rake
ci:migrate is run (8.0 only)**.
 
This migration poses a **significant risk** of breaking your GitLab
installation. Create a backup before proceeding:
#### 3. CI settings are now in GitLab
 
# Manual installation
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
If you want to use custom CI settings (e.g. change where builds are
stored), please update `/etc/gitlab/gitlab.rb` (Omnibus) or
`/home/git/gitlab/config/gitlab.yml` (Source).
 
# Omnibus installation
sudo gitlab-rake gitlab:backup:create
#### 4. Upgrade GitLab CI to 8.0
 
It's possible to speed up backup creation by skipping repositories and uploads:
Now upgrade GitLab CI to version 8.0. If you are using Omnibus packages,
this may have already happened when you upgraded GitLab to 8.0.
 
# Manual installation
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=repositories,uploads
#### 5. Disable GitLab CI on the CI server
 
# Omnibus installation
sudo gitlab-rake gitlab:backup:create SKIP=repositories,uploads
Disable GitLab CI after upgrading to 8.0.
 
#### 5. Copy secret tokens from CI
```
# On your CI server:
# Omnibus
sudo gitlab-ctl stop ci-unicorn
sudo gitlab-ctl stop ci-sidekiq
# Source
sudo service gitlab_ci stop
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec whenever --clear-crontab
```
 
The `secrets.yml` file stores encryption keys for secure variables.
### II. Moving data
 
- **Manual installations** need to copy the contents of GitLab CI's
`config/secrets.yml` file to the same file in GitLab CE:
#### 1. Database encryption key
 
```bash
# Manual installation
sudo cp /home/gitlab_ci/gitlab-ci/config/secrets.yml /home/git/gitlab/config/secrets.yml
sudo chown git:git /home/git/gitlab/config/secrets.yml
sudo chown 0600 /home/git/gitlab/config/secrets.yml
```
Move the database encryption key from your CI server to your GitLab
server. The command below will show you what you need to copy-paste to your
GitLab server. On Omnibus GitLab servers you will have to add a line to
`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you will have
to replace the contents of `/home/git/gitlab/config/secrets.yml`.
 
- **Omnibus installations** where GitLab CI and CE (or EE) are on the same
server don't need to do anything further, because the secrets are stored in
`/etc/gitlab/gitlab-secrets.json`.
```
# On your CI server:
# Omnibus
sudo gitlab-ci-rake backup:show_secrets
 
- **Omnibus installations** where GitLab CI is on a different server than CE (or
EE) will need to:
1. On the CI server, copy the `db_key_base` value from
`/etc/gitlab/gitlab-secrets.json`
1. On the CE (or EE) server, add `gitlab_ci['db_key_base'] =
"VALUE_FROM_ABOVE"` to the `/etc/gitlab/gitlab.rb` file and run `sudo
gitlab-ctl reconfigure`
# Source
cd /home/gitlab_ci/gitlab-ci
sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production
```
 
#### 6. New configuration options for `gitlab.yml`
#### 2. SQL data and build traces
 
**Note:** This step is only required for **manual installations**. Omnibus users
can [skip to the next step](#7-copy-backup-from-gitlab-ci).
Create your final CI data export. If you are converting from MySQL to
PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When
the command finishes it will print the path to your data export archive; you
will need this file later.
 
There are new configuration options available for `gitlab.yml`. View them with
the command below and apply them manually to your current `gitlab.yml`:
```
# On your CI server:
# Omnibus
sudo gitlab-ci-rake backup:create
 
git diff origin/7-14-stable:config/gitlab.yml.example origin/8-0-stable:config/gitlab.yml.example
# Source
cd /home/git/gitlab
sudo -u git -H bundle exec rake backup:create RAILS_ENV=production
```
 
The new options include configuration settings for GitLab CI.
#### 3. Copy data to the GitLab server
 
#### 7. Copy backup from GitLab CI
If you were running GitLab and GitLab CI on the same server you can skip this
step.
 
```bash
# Manual installation
sudo cp -v /home/gitlab_ci/gitlab-ci/tmp/backups/*_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups
sudo chown git:git /home/git/gitlab/tmp/backups/*_gitlab_ci_backup.tar
Copy your CI data archive to your GitLab server. There are many ways to do
this, below we use SSH agent forwarding and 'scp', which will be easy and fast
for most setups. You can also copy the data archive first from the CI server to
your laptop and then from your laptop to the GitLab server.
 
# Omnibus installation
sudo cp -v /var/opt/gitlab/ci-backups/*_gitlab_ci_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/*_gitlab_ci_backup.tar
```
# Start from your laptop
ssh -A ci_admin@ci_server.example
# Now on the CI server
scp /path/to/12345_gitlab_ci_backup.tar gitlab_admin@gitlab_server.example:~
```
 
If moving across the servers you can use `scp`.
However, this requires you to provide an authorized key or password to login to
the GitLab CE (or EE) server from the CI server. You can try to use ssh-agent
from your local machine to have that: login to your GitLab CI server using
`ssh -A`.
#### 4. Move data to the GitLab backups folder
 
```bash
# Manual installation
scp /home/gitlab_ci/gitlab-ci/tmp/backups/*_gitlab_ci_backup.tar root@gitlab.example.com:/home/git/gitlab/tmp/backup
Make the CI data archive discoverable for GitLab. We assume below that you
store backups in the default path, adjust the command if necessary.
 
# Omnibus installation
scp /var/opt/gitlab/ci-backups/*_gitlab_ci_backup.tar root@gitlab.example.com:/var/opt/gitlab/backups/
```
# On your GitLab server:
# Omnibus
sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/
 
#### 8. Import GitLab CI backup
Now you'll import the GitLab CI database dump that you created earlier into the
GitLab CE or EE database:
# Source
sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/
```
 
# Manual installation
sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production
#### 5. Import the CI data into GitLab.
 
# Omnibus installation
sudo gitlab-rake ci:migrate
This step will delete any existing CI data on your GitLab server. There should
be no CI data yet because you turned CI on the GitLab server off earlier.
 
This task will take some time.
```
# On your GitLab server:
# Omnibus
sudo gitlab-rake ci:migrate
 
This migration task automatically re-enables the CI setting that you
[disabled earlier](#2-prevent-ci-usage-during-the-migration-process).
# Source
cd /home/git/gitlab
sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production
```
 
#### 9. Start GitLab
#### 6. Restart GitLab
 
You can start GitLab CE (or EE) now and see if everything is working:
```
# On your GitLab server:
# Omnibus
sudo gitlab-ctl hup unicorn
sudo gitlab-ctl restart sidekiq
 
# Manual installation
sudo service gitlab start
# Source
sudo service gitlab reload
```
 
# Omnibus installation
sudo gitlab-ctl restart unicorn sidekiq
### III. Redirecting traffic
 
### Part III: Nginx configuration
If you were running GitLab CI with Omnibus packages and you were using the
internal NGINX configuration your CI service should now be available both at
`ci.example.com` (the old address) and `gitlab.example.com/ci`. **You are done!**
 
This section is only required for **manual installations**. Omnibus users can
[skip to the final step](#part-iv-finishing-up).
If you installed GitLab CI from source we now need to configure a redirect in
NGINX so that existing CI runners can keep using the old CI server address, and
so that existing links to your CI server keep working.
 
#### 1. Update Nginx configuration
 
@@ -296,16 +307,6 @@ You should also make sure that you can:
 
sudo /etc/init.d/nginx restart
 
### Part IV: Finishing Up
If everything went well you should be able to access your migrated CI install by
visiting `https://gitlab.example.com/ci/`. If you visit the old GitLab CI
address, you should be redirected to the new one.
**Enjoy!**
### Troubleshooting
#### Restore from backup
 
If something went wrong and you need to restore a backup, consult the [Backup
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment