V4 to V5 Guide - Sourcebot

This guide will walk you through upgrading your Sourcebot deployment from v4 to v5.

Breaking Changes

Ask Sourcebot & MCP Server relicensing

Who’s affected: Users on the free plan.

Description

Starting in v5, the following features have been relicensed from FSL to our commercial license, requiring a paid plan to use:

If your deployment uses these features and you upgrade to v5, you’ll need to activate a paid plan to keep using them.

Action Items

You can start a 14-day free trial of the paid plan directly from your deployment. No credit card is required. See the pricing page for more details. Alternatively, you can choose to stay on v4.

User role management relicensing

Who’s affected: Users on the free plan.

Description

Managing user roles now requires a paid plan. On the free plan, the default role assigned to new members joining an organization is now Owner (previously this was Member). The role assignment behaviour for users joining the organization, and the ability to manage the user’s role afterwards, is now the following:

Plan	Default role	Role management
Free	`Owner`	Not available. A user’s role cannot be changed.
Paid	`Member`	Available. Owners can promote or demote members.

This does not affect existing users in the organization. Users with the Member role will continue to have this role. This change only affects new members added to the organization.

Action Items

You can start a 14-day free trial of the paid plan directly from your deployment. No credit card is required. See the pricing page for more details. Alternatively, you can choose to stay on v4.

External Postgres and Redis instances are now required

Who’s affected: Deployments that relied on the embedded Postgres and Redis packaged in the Docker container. Docker Compose and Helm chart deployments are not affected, since both already provide their own Postgres and Redis.

Description

In v4 and earlier, the Sourcebot image shipped with a built-in Postgres database and Redis instance that started automatically when DATABASE_URL and REDIS_URL were not set. Starting in v5, these embedded services have been removed. You must now provide your own Postgres and Redis instances and point Sourcebot at them using the DATABASE_URL and REDIS_URL environment variables. If either variable is missing, the container exits at startup with an error. You need to stand up your own Postgres and Redis instances and set both variables. The simplest path is to switch to the Docker Compose or Helm chart deployment, both of which wire these up for you.

Action Items

Show Migrating Postgres

The embedded Postgres stored its data under $DATA_CACHE_DIR/db inside the container volume. This data is not migrated automatically. You need to dump it and restore it into your external Postgres instance.

Do the dump before upgrading to v5. The v5 image no longer bundles pg_dump, so you must run it while your v4 container (which still has the embedded Postgres) is running.

With your v4 deployment still running, dump the embedded sourcebot database from inside the container and copy it out. Replace sourcebot with your container name if it differs:

docker exec -t sourcebot pg_dump -U postgres -d sourcebot -Fc -f /tmp/sourcebot.dump
docker cp sourcebot:/tmp/sourcebot.dump ./sourcebot.dump

Set up an external Postgres instance for Sourcebot to use. This can be a managed Postgres service, a standalone Postgres container, the postgres service from the official docker-compose.yml, or the one provided by the Helm chart. Make sure it’s reachable from where Sourcebot runs.
(Optional) When using a database other than postgres, you need to create it:

Show optional command

createdb -U postgres my-database

The following steps assume the database name postgres. Adjust the DATABASE_URL and -d pg_restore parameter when using a different database name.

Restore the dump into the database:

pg_restore -U postgres -d postgres --no-owner ./sourcebot.dump

Set DATABASE_URL to point at the external database and start Sourcebot on v5. Sourcebot runs any outstanding schema migrations automatically at startup.

docker run \
  -e DATABASE_URL='postgresql://your-user:your-password@your-postgres-host:5432/postgres' \
  # ... your other flags
  ghcr.io/sourcebot-dev/sourcebot:latest

Show Migrating Redis

Redis only holds transient job-queue data, so there is nothing to migrate. You just need to provide an external Redis instance and point Sourcebot at it.

Set up an external Redis instance for Sourcebot to use. This can be a managed Redis service, a standalone Redis container, the redis service from the official docker-compose.yml, or the one provided by the Helm chart. Make sure it’s reachable from where Sourcebot runs.
Set REDIS_URL to point at it when you start Sourcebot on v5:

docker run \
  -e REDIS_URL='redis://your-redis-host:6379' \
  # ... your other flags
  ghcr.io/sourcebot-dev/sourcebot:latest

AUTH_SECRET and SOURCEBOT_ENCRYPTION_KEY must be set explicitly

Who’s affected: Deployments that relied on Sourcebot auto-generating these secrets (i.e. those that never set AUTH_SECRET or SOURCEBOT_ENCRYPTION_KEY). Docker Compose and Helm chart deployments that already set both are not affected.

Description

In v4 and earlier, when AUTH_SECRET or SOURCEBOT_ENCRYPTION_KEY was not set, Sourcebot generated one at startup and persisted it in plain text under $DATA_CACHE_DIR (.authjs-secret and .secret). Starting in v5, these secrets must be provided explicitly as environment variables. Sourcebot no longer generates them, and no longer reads the plaintext files. If either is missing, the container exits at startup with an error.

Set SOURCEBOT_ENCRYPTION_KEY to the same value your deployment was using. It encrypts sensitive data at rest, so a different key leaves that data undecryptable and breaks the features that depend on it. A changed AUTH_SECRET is less severe: it only signs out existing sessions.

Action Items

Show Migrating your secrets

Recover the existing values from the data volume, set them as environment variables, then delete the plaintext files. $DATA_CACHE_DIR defaults to /data/.sourcebot.

With your v4 deployment still running, print the stored values. Replace sourcebot with your container name if it differs:

docker exec sourcebot cat /data/.sourcebot/.secret
docker exec sourcebot cat /data/.sourcebot/.authjs-secret

Each file contains a single line, e.g. SOURCEBOT_ENCRYPTION_KEY="...". Copy the value between the quotes.

Set both as environment variables on your v5 deployment:

docker run \
  -e SOURCEBOT_ENCRYPTION_KEY='<value from .secret>' \
  -e AUTH_SECRET='<value from .authjs-secret>' \
  # ... your other flags
  ghcr.io/sourcebot-dev/sourcebot:latest

Delete the plaintext files from the data volume so the secrets are no longer stored on disk:

docker exec sourcebot rm /data/.sourcebot/.secret /data/.sourcebot/.authjs-secret

Sourcebot warns at startup if either file is still present.

Upgrading

Before upgrading, review the Breaking Changes section and complete any actions that apply to your deployment.

Docker Compose

Pull the latest image

docker compose pull

Restart your deployment

docker compose up -d

Helm chart

Refresh the chart repository

helm repo update

Upgrade the release

helm upgrade sourcebot sourcebot/sourcebot \
  -f values.yaml \
  --set-json "sourcebot.config=$(cat config.json)"

Staying on v4

If you’d rather not upgrade to v5, you can keep using v4 indefinitely by pinning your deployment to the final v4 release:

ghcr.io/sourcebot-dev/sourcebot:v4.17.4

Troubleshooting

Having troubles migrating from v4 to v5? Reach out to us on GitHub and we’ll try our best to help.

​Breaking Changes

​Ask Sourcebot & MCP Server relicensing

​Description

​Action Items

​User role management relicensing

​Description

​Action Items

​External Postgres and Redis instances are now required

​Description

​Action Items

​AUTH_SECRET and SOURCEBOT_ENCRYPTION_KEY must be set explicitly

​Description

​Action Items

​Upgrading

​Docker Compose

​Helm chart

​Staying on v4

​Troubleshooting

Breaking Changes

Ask Sourcebot & MCP Server relicensing

Description

Action Items

User role management relicensing

Description

Action Items

External Postgres and Redis instances are now required

Description

Action Items

AUTH_SECRET and SOURCEBOT_ENCRYPTION_KEY must be set explicitly

Description

Action Items

Upgrading

Docker Compose

Helm chart

Staying on v4

Troubleshooting