Upgrade Docker instances

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

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:

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

After you upgrade:

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

Upgrade with Docker Engine

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

Create a backup. As a minimum, back up the database and the GitLab secrets file.
Stop the running container:
```
sudo docker stop gitlab
```
Remove the existing container:
```
sudo docker rm gitlab
```

Pull the new image:

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

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

Ensure that the GITLAB_HOME environment variable is defined:
```
echo $GITLAB_HOME
```

Create the container again with the previously specified options:

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:

Create a backup. As a minimum, back up the database and the GitLab secrets file.
Edit docker-compose.yml and change the version to pull.
Download the newest release and upgrade your GitLab instance:
```
docker compose pull
docker compose up -d
```