Upgrade Docker instances

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

Before you upgrade, consult information you need before you upgrade.

Upgrade GitLab by using Docker Engine

To upgrade a GitLab instance that was installed by using Docker Engine:

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

2. Stop the running container:

   sudo docker stop gitlab

3. Remove the existing container:

   sudo docker rm gitlab

4. Pull the new image:

   GitLab Enterprise Edition

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

   GitLab Community Edition

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

5. Ensure that the GITLAB_HOME environment variable is defined:

   echo $GITLAB_HOME

6. 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 GitLab by using Docker Compose

To upgrade a GitLab instance that was installed by using 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:

   docker compose pull
   docker compose up -d