Upgrade Sourcegraph on Docker Compose

This document describes the process to update a Docker Compose Sourcegraph instance.

Standard upgrades

A standard upgrade occurs between two minor versions of Sourcegraph. If you are looking to jump forward several versions, you must perform a multi-version upgrade instead.

If you've configured Docker Compose with a release branch, please merge the upstream release tag for the next minor version into your release branch. In the following example, the release branch is being upgraded to v3.43.2.

# first, checkout the release branch
git checkout release
# fetch updates
git fetch upstream
# merge the upstream release tag into your release branch
git checkout release
git merge v3.43.2

Address any merge conflicts you might have

For each conflict, you need to reconcile any customizations you made with the updates from the new version. Use the information you gathered earlier from the change log and changes list to interpret the merge conflict and to ensure that it doesn't over-write your customizations. You may need to update your customizations to accommodate the new version.

Clone the updated release branch to your server

SSH into your instance and navigate to the appropriate folder:

# AWS
cd /home/ec2-user/deploy-sourcegraph-docker/docker-compose
# Azure, Digital Ocean, Google Cloud
cd /root/deploy-sourcegraph-docker/docker-compose

Download all the latest docker images to your local docker daemon:

docker-compose pull --include-deps

Restart Docker Compose using the new minor version along with your customizations:

docker-compose up -d --remove-orphans

Multi-version upgrades

A multi-version upgrade is a downtime-incurring upgrade from version 3.20 or later to any future version. Multi-version upgrades will run both schema and data migrations to ensure the data available from the instance remains available post-upgrade.

Before performing a multi-version upgrade:

Read our update policy to learn about Sourcegraph updates.
Find the entries that apply to the version range you're passing through in the update notes for Sourcegraph with Docker Compose.

To perform a multi-version upgrade on a Sourcegraph instance running on Docker compose:

Spin down the instance:

docker-compose stop

Spin back up each in-use local database so that the migrator can access them. Any externalized database is already accessible from the migrator so no action is needed for them.

docker-compose up -d pgsql
docker-compose up -d codeintel-db
docker-compose up -d codeinsights-db

Run the migrator upgrade command targetting the same databases as your instance. See the command documentation for additional details. In short, the migrator is invoked with a docker run command using the same compose network and using environment variables indicating the instance's databases.
Now that the data has been prepared to run against a new version of Sourcegraph, the infrastructure can be updated. The remaining steps follow the standard upgrade for Docker Compose.