Updating a single-image Sourcegraph instance (sourcegraph/server)

This document describes the exact changes needed to update a single-node Sourcegraph instance. Always refer to this page before upgrading Sourcegraph, as it comprehensively describes the steps needed to upgrade, and any manual migration steps you must perform.

  1. Read our update policy to learn about Sourcegraph updates.
  2. Find the relevant entry for your update in the update notes on this page.
  3. After checking the relevant update notes, refer to the standard upgrade procedure to upgrade your instance.

3.29 -> 3.30.3

⚠️ Users on 3.29.x are advised to upgrade directly to 3.30.3. If you have already upgraded to 3.30.0, 3.30.1, or 3.30.2 please follow this migration guide.

Standard upgrade procedure

To update, just use the newer sourcegraph/server:N.N.N Docker image (where N.N.N is the version number) in place of the older one, using the same Docker volumes. Your server’s data will be migrated automatically if needed.

You can always find the version number of the latest release at docs.sourcegraph.com in the docker run command’s image tag.

3.28 -> 3.29

Standard upgrade procedure

To update, just use the newer sourcegraph/server:N.N.N Docker image (where N.N.N is the version number) in place of the older one, using the same Docker volumes. Your server’s data will be migrated automatically if needed.

You can always find the version number of the latest release at docs.sourcegraph.com in the docker run command’s image tag.

3.27 -> 3.28

Standard upgrade procedure

To update, just use the newer sourcegraph/server:N.N.N Docker image (where N.N.N is the version number) in place of the older one, using the same Docker volumes. Your server’s data will be migrated automatically if needed.

You can always find the version number of the latest release at docs.sourcegraph.com in the docker run command’s image tag.

3.26 -> 3.27

Warning: ⚠️ Sourcegraph 3.27 now requires Postgres 12+.

If you are using an external database, upgrade your database to Postgres 12 or above prior to upgrading Sourcegraph. If you are using the embedded database, prepare your data for migration prior to upgrading Sourcegraph.

3.25 -> 3.26

Standard upgrade procedure

To update, just use the newer sourcegraph/server:N.N.N Docker image (where N.N.N is the version number) in place of the older one, using the same Docker volumes. Your server’s data will be migrated automatically if needed.

You can always find the version number of the latest release at docs.sourcegraph.com in the docker run command’s image tag.

  • As a precaution, before updating, we recommend backing up the contents of the Docker volumes used by Sourcegraph.
  • If you need a HA deployment, use the Kubernetes cluster deployment option.
  • There is currently no automated way to downgrade to an older version after you have updated. Contact support for help.

3.24 -> 3.25

  • Go 1.15 introduced changes to SSL/TLS connection validation which requires certificates to include a SAN. This field was not included in older certificates and clients relied on the CN field. You might see an error like x509: certificate relies on legacy Common Name field. We recommend that customers using Sourcegraph with an external database and and connecting to it using SSL/TLS check whether the certificate is up to date.

3.20 -> 3.21

This release introduces a second database instance, codeintel-db. If you have configured Sourcegraph with an external database, then update the CODEINTEL_PG* environment variables to point to a new external database as described in the external database documentation. Again, these must not point to the same database or the Sourcegraph instance will refuse to start.

If you wish to keep existing LSIF data

If you had LSIF data uploaded prior to upgrading to 3.21.0, there is a background migration that moves all existing LSIF data into the codeintel-db upon upgrade. Once this process completes, the /lsif-storage/dbs directory on the precise-code-intel-bundle-manager volume should be empty, and the bundle manager should print the following log message:

Migration to Postgres has completed. All existing LSIF bundles have moved to the path /lsif-storage/db-backups and can be removed from the filesystem to reclaim space.

Wait for the above message to be printed in docker logs precise-code-intel-bundle-manager before upgrading to the next Sourcegraph version.

Turn off database secrets encryption

In Sourcegraph version 3.20, we would automatically generate a secret key file (/var/lib/sourcegraph/token) inside the container for encrypting secrets stored in the database. However, it is not yet ready for general use and format of the secret key file might change. Therefore, it is best to delete the secret key file (/var/lib/sourcegraph/token) and turn off the database secrets encryption.

3.16 -> 3.17

  • There was a bug in release that caused the version displayed on the site-admin/update page to be 0.0.0+dev instead of 3.17.0. This issue was fixed in the 3.17.2 release. We recommend that you avoid this issue by upgrading past 3.17.0 to 3.17.2 using the Standard upgrade procedure listed below.

Standard upgrade procedure

To update, just use the newer sourcegraph/server:N.N.N Docker image (where N.N.N is the version number) in place of the older one, using the same Docker volumes. Your server’s data will be migrated automatically if needed.

You can always find the version number of the latest release at docs.sourcegraph.com in the docker run command’s image tag.

  • As a precaution, before updating, we recommend backing up the contents of the Docker volumes used by Sourcegraph.
  • If you need a HA deployment, use the Kubernetes cluster deployment option.
  • There is currently no automated way to downgrade to an older version after you have updated. Contact support for help.