Updating a pure-Docker Sourcegraph cluster

This document describes the exact changes needed to update a pure-Docker Sourcegraph cluster. Each section comprehensively describes the changes needed in Docker images, environment variables, and added/removed services. 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. If the notes indicate a patch release exists, target the highest one.

Unreleased

v5.2.6 ➔ v5.2.7

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.7

For non-standard replica builds:

Notes:

v5.2.5 ➔ v5.2.6

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.6

For non-standard replica builds:

Notes:

v5.2.4 ➔ v5.2.5

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.5 For non-standard replica builds:

Notes:

v5.2.3 ➔ v5.2.4

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.4 For non-standard replica builds:

Notes:

v5.2.2 ➔ v5.2.3

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.3

For non-standard replica builds:

Notes:

v5.2.1 ➔ v5.2.2

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.2

For non-standard replica builds:

Notes:

v5.2.0 ➔ v5.2.1

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.1

For non-standard replica builds:

Notes:

v5.1.9 ➔ v5.2.0

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.2.0

For non-standard replica builds:

Notes:

v5.1.8 ➔ v5.1.9

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.9

For non-standard replica builds:

Notes:

v5.1.7 ➔ v5.1.8

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.8

For non-standard replica builds:

Notes:

v5.1.6 ➔ v5.1.7

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.7

For non-standard replica builds:

Notes:

v5.1.5 ➔ v5.1.6

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.6

For non-standard replica builds:

Notes:

v5.1.4 ➔ v5.1.5

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.5

For non-standard replica builds:

Notes:

v5.1.3 ➔ v5.1.4

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.4

For non-standard replica builds:

Notes:

v5.1.2 ➔ v5.1.3

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.3

For non-standard replica builds:

Notes:

v5.1.1 ➔ v5.1.2

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.2

For non-standard replica builds:

Notes:

v5.1.0 ➔ v5.1.1

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.1

For non-standard replica builds:

Notes:

v5.0.6 ➔ v5.1.0

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.1.0

For non-standard replica builds:

Notes:

v5.0.5 ➔ v5.0.6

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.6

For non-standard replica builds:

Notes:

v5.0.4 ➔ v5.0.5

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.5

For non-standard replica builds:

Notes:

v5.0.3 ➔ v5.0.4

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.4

For non-standard replica builds:

Notes:

v5.0.2 ➔ v5.0.3

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.3

For non-standard replica builds:

Notes:

v5.0.1 ➔ v5.0.2

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.2

For non-standard replica builds:

Notes:

v5.0.0 ➔ v5.0.1

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.1

For non-standard replica builds:

Notes:

v4.5.1 ➔ v5.0.0

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v5.0.0

For non-standard replica builds:

Notes:

v4.5.0 ➔ v4.5.1

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v4.5.1

For non-standard replica builds:

Notes:

v4.4.2 ➔ v4.5.0

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v4.5.0

For non-standard replica builds:

Notes:

  • This release introduces a background job that will convert all LSIF data into SCIP. This migration is irreversible and a rollback from this version may result in loss of precise code intelligence data. Please see the migration notes for more details.

v4.4.1 ➔ v4.4.2

As a template, perform the same actions as the following diff in your own deployment: Upgrade to v4.4.2

For non-standard replica builds:

Notes:

v4.4.0 ➔ v4.4.1

As a template, perform the same actions as the following diffs in your own deployment:

v4.3.1 ➔ v4.4.1

As a template, perform the same actions as the following diffs in your own deployment:

  • ➔ v4.4.0

  • Users attempting a multi-version upgrade to v4.4.0 may be affected by a known bug in which an outdated schema migration is included in the upgrade process. This issue is fixed in patch v4.4.2

    • The error will be encountered while running upgrade, and contains the following text: "frontend": failed to apply migration 1648115472.
      • To resolve this issue run migrator with the args 'add-log', '-db=frontend', '-version=1648115472'.
      • If migrator was stopped while running upgrade the next run of upgrade will encounter drift, this drift should be disregarded by providing migrator with the --skip-drift-check flag.

v4.2 ➔ v4.3.1

As a template, perform the same actions as the following diffs in your own deployment:

v4.1 ➔ v4.2.1

  • minio has been replaced with blobstore. Please see the update notes here

As a template, perform the same actions as the following diffs in your own deployment:

v4.0 ➔ v4.1.3

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

v3.43 ➔ v4.0

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

v3.42 ➔ v3.43

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.43.1
  • v3.43.2

v3.41 ➔ v3.42

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.42.1
  • v3.42.2

v3.40 ➔ v3.41

As a template, perform the same actions as the following diffs in your own deployment:

v3.39 ➔ v3.40

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.40.1
  • v3.40.2

Notes:

  • A fix that corrects the default behavior of the migrator service is included in this release. An attempt to standardize CLI packages in v3.39.0 unintentionally broke the default behavior. In order to guard against this, all command line arguments are explicitly set in the deployment manifest.
  • CAUTION Added the ability to customize postgres server configuration by mounting external configuration files. If you have customized the config in any way, you should copy your changes to the added postgresql.conf files sourcegraph/deploy-sourcegraph-docker#806

v3.38 ➔ v3.39

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.39.1

Notes:

  • In this release we need to remove timescaledb from shared_preload_libraries configuration in codeinsights-db's postgresql.conf. This step will be performed automatically. It can be performed manually instead of run as part of the deploy script.

v3.37 ➔ v3.38

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.38.1

Notes:

  • This release adds the requirement that the environment variables SRC_GIT_SERVERS, SEARCHER_URL, SYMBOLS_URL, and INDEXED_SEARCH_SERVERS are set for the worker process.

v3.36 ➔ v3.37

As a template, perform the same actions as the following diffs in your own deployment:

Notes:

  • This release adds a new container that runs database migrations (migrator) independently of the frontend container. Confirm the environment variables on this new container match your database settings.

v3.35 ➔ v3.36

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.36.1
  • v3.36.3
  • v3.36.3

v3.34 ➔ v3.35

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.35.1
  • v3.35.2

Notes:

  • The query-runner service has been decomissioned in the 3.35.0 release. You can safely remove the query-runner service from your installation.
  • There is a known issue with the Code Insights out-of-band settings migration not reaching 100% complete when encountering deleted users or organizations.

v3.33 ➔ v3.34

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.34.1
  • v3.34.2

v3.32 ➔ v3.33

As a template, perform the same actions as the following diffs in your own deployment:

v3.31 ➔ v3.32

As a template, perform the same actions as the following diffs in your own deployment:

v3.30 ➔ v3.31

WARNING: This upgrade must originate from v3.30.3.

Notes:

  • The built-in main Postgres (pgsql) and codeintel (codeintel-db) databases have switched to an alpine-based Docker image. Upon upgrading, Sourcegraph will need to re-index the entire database. All users that use our bundled (built-in) database instances must read through the 3.31 upgrade guide before upgrading.

v3.29 ➔ v3.30

WARNING: If you have already upgraded to 3.30.0, 3.30.1, or 3.30.2 please follow this migration guide.

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.30.1
  • v3.30.2
  • v3.30.3

v3.28 ➔ v3.29

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.29.1

Notes:

  • This upgrade adds a new worker service that runs a number of background jobs that were previously run in the frontend service. See notes on deploying workers for additional details. Good initial values for CPU and memory resources allocated to this new service should match the frontend service.

v3.27 ➔ v3.28

As a template, perform the same actions as the following diffs in your own deployment:

v3.26 ➔ v3.27

WARNING: Sourcegraph 3.27 now requires Postgres 12+.

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.27.1
  • v3.27.2
  • v3.27.3
  • v3.27.4

Notes:

  • If you are using an external database, upgrade your database to Postgres 12.5 or above prior to upgrading Sourcegraph. No action is required if you are using the supplied supplied database images.

v3.26 ➔ v3.26

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.26.1
  • v3.26.2

v3.24 ➔ v3.25

As a template, perform the same actions as the following diffs in your own deployment:

Notes:

  • If you are connecting to an external Postgres database using SSL/TLS: 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 connecting to it using SSL/TLS check whether the certificate is up to date.
  • Confirm that codeinsights-db-disk has the correct file permissions via the following command.
BASH
sudo chown -R 999:999 ~/sourcegraph-docker/codeinsights-db-disk/

v3.23 ➔ v3.24

As a template, perform the same actions as the following diffs in your own deployment:

v3.22 ➔ v3.23

As a template, perform the same actions as the following diffs in your own deployment:

v3.21 ➔ v3.22

As a template, perform the same actions as the following diffs in your own deployment:

Notes:

  • This upgrade removes the code intel bundle manager. This service has been deprecated and all references to it have been removed.
  • This upgrade also adds a MinIO container that doesn't require any custom configuration. You can find more detailed documentation here.

v3.20 ➔ v3.21

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.21.1
  • v3.21.2

Notes*:

  • This upgrade includes a new code-intel DB (deploy-codeintel-db.sh) and a new service minio (deploy-minio.sh) to store precise code intel indexes.
  • There is a new environment variable for frontend and frontend-internal called CODEINTEL_PGHOST.

v3.19 ➔ v3.20

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.20.1

Notes:

  • Confirm that lsif-server-disk has the correct file permissions via the following command.
BASH
sudo chown -R 100:101 ~/sourcegraph-docker/lsif-server-disk/ ~/sourcegraph-docker/lsif-server-disk/

v3.18 ➔ v3.19

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.19.1

Notes:

  • Confirm that lsif-server-disk has the correct file permissions via the following command.
BASH
sudo chown -R 100:101 ~/sourcegraph-docker/lsif-server-disk/ ~/sourcegraph-docker/lsif-server-disk/

v3.17 ➔ v3.18

As a template, perform the same actions as the following diffs in your own deployment:

Notes:

  • deploy-grafana.sh and deploy-prometheus.sh had environment variables changed, otherwise only image tags have changed.

v3.16 ➔ v3.17

As a template, perform the same actions as the following diffs in your own deployment:

Patch releases:

  • v3.17.2

v3.15 ➔ v3.16

As a template, perform the same actions as this diff in your own deployment.

Steps:

  1. Change 3.15.1 image tags to 3.16.0.
  2. Update prometheus/prometheus_targets.yml as shown here.

v3.14 ➔ v3.15

Patch releases:

  • v3.15.1

Steps:

  1. Update environment variables
  • On frontend and frontend-internal containers, remove the LSIF_SERVER_URL environment variable.
  • On frontend and frontend-internal containers, set PRECISE_CODE_INTEL_API_SERVER_URL=http://precise-code-intel-api-server:3186
  • On all containers, change JAEGER_AGENT_HOST=jaeger-agent to JAEGER_AGENT_HOST=jaeger
  1. Remove all old container deployments
  • jaeger-agent container (deploy-jaeger-agent.sh)
  • jaeger-cassandra container (deploy-jaeger-cassandra.sh)
  • jaeger-collector container (deploy-jaeger-collector.sh)
  • jaeger-query container (deploy-jaeger-query.sh)
  • lsif-server container (deploy-lsif-server.sh)
  1. Add new container deployments
  1. Update prometheus_targets.yml by replacing lsif-server:3186 with precise-code-intel-api-server:3186 and replacing lsif-server:3187 with precise-code-intel-bundle-manager:3187
  2. Update image tags to 3.15.1. Change all sourcegraph/ image tags to 3.15.1. This includes all images you previously had as 3.14.2 AND all sourcegraph/<service> images:
  • index.docker.io/sourcegraph/grafana:3.15.1
  • index.docker.io/sourcegraph/prometheus:3.15.1
  • index.docker.io/sourcegraph/redis-cache:3.15.1
  • index.docker.io/sourcegraph/redis-store:3.15.1
  • index.docker.io/sourcegraph/pgsql:3.15.1

The following images have been renamed AND use Sourcegraph versions now (their container names and shell script names remain the same for now):

DIFF
- index.docker.io/sourcegraph/syntect_server:c0297a1@sha256:333abb45cfaae9c9d37e576c3853843b00eca33a40a7c71f6b93211ed96528df
+ index.docker.io/sourcegraph/syntax-highlighter:3.15.1
 
- index.docker.io/sourcegraph/zoekt-indexserver:0.0.20200318141948-0b140b7@sha256:b022fd7e4884a71786acae32e0ec8baf785c18350ebf5d574d52335a346364f9
+ index.docker.io/sourcegraph/search-indexer:3.15.1
 
- index.docker.io/sourcegraph/zoekt-webserver:0.0.20200318141342-0b140b7@sha256:0d0fbce55b51ec7bdd37927539f50459cd0f207b7cf219ca5122d07792012fb1
+ index.docker.io/sourcegraph/indexed-searcher:3.15.1