gitlabhq/doc/install/docker/upgrade.md

stage, group, info, title

stage	group	info	title
GitLab Delivery	Self Managed	To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments	Upgrade Docker-based installations

{{< details >}}

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

{{< /details >}}

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

Upgrade GitLab using Docker Engine

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

   sudo docker pull gitlab/gitlab-ee:<version>-ee.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.

Refer to the GitLab Upgrade recommendations when upgrading to different versions.

Upgrade GitLab using Docker compose

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

1. Take 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
   

Downgrade GitLab

The restore overwrites all newer GitLab database content with the older state. A downgrade is only recommended where necessary. For example, if post-upgrade tests reveal problems that cannot be resolved quickly.

{{< alert type="warning" >}}

You must have at least a database backup created with the exact same version and edition you are downgrading to. The backup is required to revert the schema changes (migrations) made during the upgrade.

{{< /alert >}}

To downgrade GitLab shortly after an upgrade:

1. Follow the upgrade procedure, by specifying an earlier version than you have installed.

2. Restore the database backup you made before the upgrade.

   • Follow the restore steps for Docker images, including stopping Puma and Sidekiq. Only the database must be restored, so add SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state to the gitlab-backup restore command line arguments.