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

Upgrade notes for the next version will appear here.

v4.3 ➔ v4.4

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:

• Customer Replica 1: ➔ v4.4.2

Notes:

v4.4.0 ➔ v4.4.1

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

• ➔ v4.4.1

v4.3.1 ➔ v4.4.1

Upgrade notes for the next version will appear here.

v4.2 ➔ v4.3.1

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

• ➔ v4.3.1

v4.1 ➔ v4.2.1

• minio has been replaced with blobstore. Please see the update notes here: https://docs.sourcegraph.com/admin/how-to/blobstore_update_notes

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

• ➔ v4.2.0

v4.0 ➔ v4.1.3

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

• ➔ v4.1.0

Patch releases:

• v4.1.1

v3.43 ➔ v4.0

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

• ➔ v4.0.0

Patch releases:

• ➔ v4.0.1

v3.42 ➔ v3.43

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

• ➔ v3.43.0

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:

• ➔ v3.42.0

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.41.0

v3.39 ➔ v3.40

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

• -> 3.40.0
• -> 3.40.2

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:

• -> 3.39.0
• -> 3.39.1

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:

• ➔ v3.38.0
• ➔ v3.38.1

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:

• ➔ v3.37.0

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. Read more about manual operation of the migrator

v3.35 ➔ v3.36

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

• ➔ v3.36.1
• ➔ v3.36.2
• ➔ v3.36.3

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:

• ➔ v3.35.0
• ➔ v3.35.1
• ➔ v3.35.2

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:

• ➔ v3.34.2

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.33.0

v3.31 ➔ v3.32

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

• ➔ v3.32.0

v3.30 ➔ v3.31

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

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

• ➔ v3.30.0

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:

• ➔ v3.29.1

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.28.0

v3.26 ➔ v3.27

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

• ➔ v3.27.4

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:

• ➔ v3.26.0
• ➔ v3.26.2

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:

• ➔ v3.25.0

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.
  • AWS RDS customers please reference AWS' documentation on updating the SSL/TLS certificate for steps to rotate your certificate.
• Confirm that codeinsights-db-disk has the correct file permissions via the following command.

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.24.0

v3.22 ➔ v3.23

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

• ➔ v3.23.0

v3.21 ➔ v3.22

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

• ➔ v3.22.0

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 in https://docs.sourcegraph.com/admin/external_services/object_storage.

v3.20 ➔ v3.21

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

• ➔ v3.21.2

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:

• ➔ v3.20.1

Patch releases:

• v3.20.1

Notes:

• Confirm that lsif-server-disk has the correct file permissions via the following command.

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:

• ➔ v3.19.1

Patch releases:

• v3.19.1

Notes:

• Confirm that lsif-server-disk has the correct file permissions via the following command.

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:

• ➔ v3.18.0

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:

• ➔ v3.17.2

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

• Add a single jaeger container following this spec
• Add a single precise-code-intel-api-server container following this spec
• Add a single precise-code-intel-bundle-manager container following this spec
• Add a single precise-code-intel-worker container following this spec

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):

- 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