Upgrade Sourcegraph on Docker Compose
⚠️ We recommend new users use our machine image or script-install instructions, which are easier and offer more flexibility when configuring Sourcegraph. Existing customers can reach out to our Customer Engineering team [email protected] if they wish to migrate to these deployment models.
This document describes the process to update a Docker Compose Sourcegraph instance.
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
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 any pods that access the database. The easiest way to do this is to shut down the instance entirely:
docker-compose stopin the directory with the
- If upgrading from 3.26 or before to 3.27 or later, the
codeintel-dbdatabases must be upgraded from Postgres 11 to Postgres 12. If this step is not performed, then the following upgrade procedure will fail fast (and leave all existing data untouched).
- If using an external database, follow the upgrading external PostgreSQL instances guide.
- Otherwise, perform the following steps from the upgrading internal Postgres instances guide:
- It's assumed that your fork of
deploy-sourcegraph-dockeris up to date with your instance's current version. Pull the upstream changes for
v3.27.0and resolve any git merge conflicts. We need to temporarily boot the containers defined at this specific version to rewrite existing data to the new Postgres 12 format.
docker-compose up pgsqlto launch new Postgres 12 containers and rewrite the old Postgres 11 data. This may take a while, but streaming container logs should show progress.
- Wait until the database container is accepting connections. Once ready, run the command
docker exec pgsql -- psql -U sg -c 'REINDEX database sg;'to repair indexes that were silently invalidated by the previous data rewrite step. If you skip this step, then some data may become inaccessible under normal operation, the following steps are not guaranteed to work, and data loss will occur.
- Follow the same steps for the
docker-compose up codeintel-dbto launch Postgres 12.
docker exec codeintel-db -- pgsql -U sg -c 'REINDEX database sg;'to reindex the database.
- It's assumed that your fork of
- Pull the upstream changes for the target instance version and resolve any git merge conflicts. The standard upgrade procedure describes this step in more detail.
- If using local database instances, start the containers now via
docker-compose up -d pgsql codeintel-db codeinsights-db. The following migrator command will start these containers on-demand if this step is skipped, but running them separately will make startup errors more apparent.
- Follow the instructions on how to run the migrator job in Docker Compose to perform the upgrade migration. For specific documentation on the
upgradecommand, see the command documentation. The following specific steps are an easy way to run the upgrade command:
- Edit the definition of the
migratorcontainer in the
docker-compose.yamlso that the value of the
commandkey is set to
['upgrade', '--from=<old version>', '--to=<new version>']. It is recommended to also add the
--dry-runflag on a trial invocation to detect if there are any issues with database connection, schema drift, or mismatched versions that need to be addressed.
- Run the upgrade via
docker-compose up migratorand wait for it to complete.
- Reset the
commandkey altered in the previous steps to
['up']so that the container initialization process will work as expected.
- The remaining infrastructure can now be updated. The standard upgrade procedure describes this step in more detail.
docker-compose pull --include-depsto pull new images.
docker-compose up -d --remove-orphansto start the containers of the updated instance.