Omnibus Docker

An upgrade replaces the container with one created from the new image tag; the volumes stay, and the instance data and configuration on them are migrated on the first start. Version order and background migrations are described in Overview.

Before the upgrade

Create a backup of the data and of the configuration, as described in Omnibus Docker, and check that the archives are outside the host.

Write down the tag the container runs, because the rollback returns to it:

docker inspect --format '{{.Config.Image}}' code

Replacing the container

Every tag names a version, and no tag follows the latest one, so the target version is named explicitly.

1. Pull the image of the target version:

   docker pull <REGISTRY>/<FLAVOR>:<VERSION>

2. Stop and remove the container. The volumes are host directories and stay in place:

   docker stop code
   docker rm code

3. Create the container from the new tag with the same name, ports, volumes and environment variables as in Quick start:

   docker run -d --name code \
     --shm-size 256m \
     -p 80:80 -p 443:443 -p 22:22 \
     -e GITLAB_OMNIBUS_CONFIG="external_url 'http://<HOSTNAME>'" \
     -v /srv/code/config:/etc/gitlab \
     -v /srv/code/logs:/var/log/gitlab \
     -v /srv/code/data:/var/opt/gitlab \
     <REGISTRY>/<FLAVOR>:<VERSION>

4. Follow the start. The database migrations run during the configuration, and the instance answers 502 until it finishes:

   docker logs -f code

5. Check the version and the services:

   docker logs code | grep 'Current version'
   docker exec code gitlab-ctl status
   docker inspect --format '{{.State.Health.Status}}' code

Checks on the first start after the upgrade

The start-up script reads the version of the data on the volume and compares it with the version in the image. When the instance cannot move to the new version in one step, the output names the version to install first and the start stops: run the tag of that version, wait for the background migrations to finish, then run the target tag.

After the configuration, the script brings the database to the PostgreSQL version of the new image. A failed database upgrade is rolled back, and the container exits with the message Upgrading the existing database failed and was reverted. Create the container with -e GITLAB_SKIP_PG_UPGRADE=true to bring the instance up on the current PostgreSQL version, and upgrade the database separately.

Background migrations continue on the running instance after the upgrade and have to finish before the next one, as described in Overview.

Rollback

The new version has migrated the data on the volumes, so returning to the previous image tag needs the backup taken before the upgrade.

1. Stop and remove the container:

   docker stop code
   docker rm code

2. Create the container from the previous tag with the same volumes.

3. Restore the data from the backup taken before the upgrade, as described in Omnibus Docker.

Additional resources

• Overview
• Omnibus Docker