Upgrade Docker instances

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed

{{< /details >}}

Upgrade a Docker-based instance to a later version of GitLab.

Prerequisites

Before you upgrade a Docker instance, you must first read required information and perform required steps.

Upgrade a Docker-based instance

To upgrade a Docker-based instance:

1. Consider turning on maintenance mode during the upgrade.
2. Pause running CI/CD pipelines and jobs.
3. Upgrade GitLab Runner to the same version as your target GitLab version.
4. Upgrade GitLab itself by either:
   • Using Docker Engine.
   • Using Docker Compose.

After you upgrade:

1. Unpause running CI/CD pipelines and jobs.
2. If enabled, turn off maintenance mode.
3. Run upgrade health checks.

Upgrade with Docker Engine

To upgrade a GitLab instance that was installed with Docker Engine:

1. Create a backup. As a minimum, back up the database and the GitLab secrets file.

2. Stop the running container:

   shellCopy

   sudo docker stop gitlab
   

3. Remove the existing container:

   shellCopy

   sudo docker rm gitlab
   

4. Pull the new image:

   {{< tabs >}}

   {{< tab title="GitLab Enterprise Edition" >}}

   shellCopy

   sudo docker pull gitlab/gitlab-ee:<version>-ee.0
   

   {{< /tab >}}

   {{< tab title="GitLab Community Edition" >}}

   shellCopy

   sudo docker pull gitlab/gitlab-ce:<version>-ce.0
   

   {{< /tab >}}

   {{< /tabs >}}

5. Ensure that the GITLAB_HOME environment variable is defined:

   shellCopy

   echo $GITLAB_HOME
   

6. Create the container again with the previously specified options:

   shellCopy

   sudo docker run --detach \
   --hostname gitlab.example.com \
   --publish 443:443 --publish 80:80 --publish 22:22 \
   --name gitlab \
   --restart always \
   --volume $GITLAB_HOME/config:/etc/gitlab \
   --volume $GITLAB_HOME/logs:/var/log/gitlab \
   --volume $GITLAB_HOME/data:/var/opt/gitlab \
   --shm-size 256m \
   gitlab/gitlab-ee:<version>-ee.0
   

On the first run, GitLab reconfigures and upgrades itself.

Upgrade with Docker Compose

To upgrade a GitLab instance that was installed with Docker Compose:

1. Create a backup. As a minimum, back up the database and the GitLab secrets file.

2. Edit docker-compose.yml and change the version to pull.

3. Download the newest release and upgrade your GitLab instance:

   shellCopy

   docker compose pull
   docker compose up -d