Updating a Docker Compose Sourcegraph instance

This page lists the changes that are relevant for upgrading Sourcegraph on Docker Compose. You can also view the product changelog.

Upgrade procedure

Read our update policy to learn about Sourcegraph updates.
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.
After checking the relevant update notes, refer to the standard upgrade procedure to upgrade your instance.

Multi-version upgrade procedure

Read our update policy to learn about Sourcegraph updates.
Find the relevant entries for your update in the update notes on this page. If the notes indicate a patch release exists, target the highest one. These notes may contain relevant information about the infrastructure update such as resource requirement changes or versions of depencies (Docker, Docker Compse, externalized databases).
After checking the relevant update notes, refer to the multi-version upgrade procedure to upgrade your instance.

Unreleased

Upgrade notes for the next version will appear here.

v4.4.1 ➔ v4.4.2

Notes:

v4.3 ➔ v4.4.1

Upgrade notes for the next version will appear here.

v4.2 ➔ v4.3.1

Upgrade notes for the next version will appear here.

v4.1 ➔ v4.2.1

Upgrade notes for the next version will appear here.

This upgrade adds the node-exporter deployment, which collects crucial machine-level metrics that help Sourcegraph scale your deployment.

v4.0 ➔ v4.1.3

Upgrade notes for the next version will appear here.

v3.43 ➔ v4.0

Target the tag v4.0.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v4.0.1

Notes:

jaeger (deployed with the jaeger-all-in-one image) has been removed in favor of an OpenTelemetry Collector DaemonSet + Deployment configuration. See Configure a tracing backend
Exporting traces to an external observability backend is now available. Read the documentation to configure.
The bundled Jaeger instance is now disabled by default. It can be enabled if you do not wish to utilise your own external tracing backend.

v3.42 ➔ v3.43

Target the tag v3.43.2 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.43.1
v3.43.2

v3.41 ➔ v3.42

Target the tag v3.42.2 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.42.1
v3.42.2

v3.40 ➔ v3.41

Target the tag v3.41.0 when fetching upstream from deploy-sourcegraph-docker.

Notes:

caddy is upgraded to version 2.5.1 and contains a breaking change from version 2.5.0. Incoming X-Forwarded-* headers will no longer be trusted automatically. In order to preserve existing product functionality, the Caddyfile was updated to trust all incoming X-Forwarded-* headers. #828
The Postgres DBs frontend and codeintel-db are now given 1 hour to begin accepting connections before Kubernetes restarts the containers. #4136

v3.39 ➔ v3.40

Target the tag v3.40.2 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.40.1
v3.40.2

Notes:

cadvisor now defaults to run in privileged mode. This allows cadvisor to collect out of memory events happening to containers which can be used to discover underprovisoned resources. #804

v3.38 ➔ v3.39

Target the tag v3.39.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.39.1

Notes:

We made a number of changes to our built-in postgres databases (the pgsql, codeintel-db, and codeinsights-db container)
- 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#792.
- Increased the minimal memory requirement of pgsql and codeintel-db from 2GB to 4GB. -codeinsights-db container no longer uses TimescaleDB and is now based on the standard Postgres image sourcegraph/deploy-sourcegraph-docker#780. Metrics scraping is also enabled.

v3.37 ➔ v3.38

Target the tag v3.38.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.38.1

Notes:

Minimum version of 1.29 for docker compose is required for this update
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

Target the tag v3.37.0 when fetching upstream from deploy-sourcegraph-docker.

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

Target the tag v3.36.0 when fetching upstream from deploy-sourcegraph-docker.

v3.34 ➔ v3.35

Target the tag v3.35.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.35.1

Notes:

The query-runner service has been decommissioned in the 3.35 release and will be removed during the upgrade. To delete the query-runner service, specify --remove-orphans to your docker-compose command.
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

Target the tag v3.34.0 when fetching upstream from deploy-sourcegraph-docker.

v3.32 ➔ v3.33

Target the tag v3.33.0 when fetching upstream from deploy-sourcegraph-docker.

v3.31 ➔ v3.32

Target the tag v3.32.0 when fetching upstream from deploy-sourcegraph-docker.

v3.30 ➔ v3.31

Target the tag v3.31.2 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.31.1
v3.31.2

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

Target the tag v3.30.3 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.30.1
v3.30.2
v3.30.3

v3.28 ➔ v3.29

Target the tag v3.29.0 when fetching upstream from deploy-sourcegraph-docker.

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

Target the tag v3.28.0 when fetching upstream from deploy-sourcegraph-docker.

Notes:

The memory requirements for redis-cache and redis-store have been increased by 1GB. See https://github.com/sourcegraph/deploy-sourcegraph-docker/pull/373 for more context.

v3.26 ➔ v3.27

Target the tag v3.27.0 when fetching upstream from deploy-sourcegraph-docker.

Notes:

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

v3.25 ➔ v3.26

Target the tag v3.26.0 when fetching upstream from deploy-sourcegraph-docker.

v3.24 ➔ v3.25

Target the tag v3.25.0 when fetching upstream from deploy-sourcegraph-docker.

Notes:

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.
- AWS RDS customers please reference AWS' documentation on updating the SSL/TLS certificate for steps to rotate your certificate.

v3.23 ➔ v3.24

Target the tag v3.24.0 when fetching upstream from deploy-sourcegraph-docker.

v3.22 ➔ v3.23

Target the tag v3.23.0 when fetching upstream from deploy-sourcegraph-docker.

v3.21 ➔ v3.22

Target the tag v3.22.0 when fetching upstream from deploy-sourcegraph-docker.

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

Target the tag v3.21.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.21.1

Notes:

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.

v3.19 ➔ v3.20

Target the tag v3.20.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.20.1

v3.18 ➔ v3.19

Target the tag v3.19.2 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.19.1
v3.19.2

v3.17 ➔ v3.18

Target the tag v3.18.0-1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.18.0-1

v3.16 ➔ v3.17

Patch releases:

Target the tag v3.17.2 when fetching upstream from deploy-sourcegraph-docker.

v3.17.1
v3.17.2

v3.15 ➔ v3.16

Target the tag v3.16.0 when fetching upstream from deploy-sourcegraph-docker.

v3.14 ➔ v3.15

Target the tag v3.15.1 when fetching upstream from deploy-sourcegraph-docker.

Patch releases:

v3.15.1