From 072fd967c48014f2862bba03bc9be293b6685a67 Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 14:30:59 -0700 Subject: [PATCH 1/7] chore: remove embedded Postgres and Redis from the Docker image As of v5, Sourcebot no longer ships an embedded Postgres or Redis. External instances are now required via DATABASE_URL and REDIS_URL. - Dockerfile: drop postgresql16/redis packages, DATABASE_DATA_DIR/ REDIS_DATA_DIR env, postgres/redis users, and /run/postgresql setup - entrypoint.sh: hard-fail with guidance when DATABASE_URL/REDIS_URL are unset; remove embedded init/startup blocks - supervisord.conf: remove the redis program - docs: mark DATABASE_URL/REDIS_URL required, drop data-dir vars, document the breaking change and data migration in the v4-to-v5 guide - CHANGELOG: note the breaking change Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 1 + Dockerfile | 11 +- .../configuration/environment-variables.mdx | 6 +- docs/docs/upgrade/v4-to-v5-guide.mdx | 103 ++++++++++++++++-- entrypoint.sh | 79 +++----------- supervisord.conf | 10 -- 6 files changed, 114 insertions(+), 96 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4f415d75..774d9e693 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Redesigned the app layout with a new collapsible sidebar navigation, replacing the previous top navigation bar. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Expired offline license keys no longer crash the process. An expired key now degrades to the unlicensed state. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Improved the `setup-sourcebot` wizard: prompts for a setup directory, clarifies that secrets are stored locally in `.env`, switches multi-select to Tab, hides "No results" until a real search runs, and detects/cleans up conflicting Docker deployments and volumes before starting. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) ### Fixed - Fixed git "dubious ownership" errors when the container runs as a non-root user by setting `safe.directory` at the system level instead of the global (root-only) level. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) diff --git a/Dockerfile b/Dockerfile index 3244f35fd..6c6b2439f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -163,8 +163,6 @@ ENV NODE_ENV=production ENV NEXT_TELEMETRY_DISABLED=1 ENV DATA_DIR=/data ENV DATA_CACHE_DIR=$DATA_DIR/.sourcebot -ENV DATABASE_DATA_DIR=$DATA_CACHE_DIR/db -ENV REDIS_DATA_DIR=$DATA_CACHE_DIR/redis ENV SOURCEBOT_PUBLIC_KEY_PATH=/app/public.pem # PAPIK = Project API Key # Note that this key does not need to be kept secret, so it's not @@ -180,7 +178,7 @@ ENV SOURCEBOT_LOG_LEVEL=info # ENV SOURCEBOT_TELEMETRY_DISABLED=1 # Configure dependencies -RUN apk add --no-cache git ca-certificates bind-tools tini jansson wget supervisor uuidgen curl perl jq redis postgresql16 postgresql16-contrib openssl util-linux unzip && \ +RUN apk add --no-cache git ca-certificates bind-tools tini jansson wget supervisor uuidgen curl perl jq openssl util-linux unzip && \ apk upgrade --no-cache # Remove npm (unused — we use Yarn). The Node.js base image bundles npm @@ -200,8 +198,6 @@ ARG GID=1500 # The container can be run as root (default) or as sourcebot user using docker run --user RUN addgroup -g $GID sourcebot && \ adduser -D -u $UID -h /app -S sourcebot && \ - adduser sourcebot postgres && \ - adduser sourcebot redis && \ chown -R sourcebot /app && \ adduser sourcebot node && \ mkdir /var/log/sourcebot && \ @@ -252,11 +248,6 @@ COPY --chown=sourcebot:sourcebot --from=shared-libs-builder /app/packages/queryL # Fixes git "dubious ownership" issues when the volume is mounted with different permissions to the container. RUN git config --system safe.directory "*" -# Configure the database -RUN mkdir -p /run/postgresql && \ - chown -R postgres:postgres /run/postgresql && \ - chmod 775 /run/postgresql - # Make app directory accessible to both root and sourcebot user RUN chown -R sourcebot /app \ && chgrp -R 0 /app \ diff --git a/docs/docs/configuration/environment-variables.mdx b/docs/docs/configuration/environment-variables.mdx index 396c4cf36..bcaee8eed 100644 --- a/docs/docs/configuration/environment-variables.mdx +++ b/docs/docs/configuration/environment-variables.mdx @@ -22,13 +22,11 @@ The following environment variables allow you to configure your Sourcebot deploy | `CONFIG_PATH` | `-` |

The container relative path to the declarative configuration file. See [this doc](/docs/configuration/declarative-config) for more info.

| | `DATA_CACHE_DIR` | `$DATA_DIR/.sourcebot` |

The root data directory in which all data written to disk by Sourcebot will be located.

| | `DATA_DIR` | `/data` |

The directory within the container to store all persistent data. Typically, this directory will be volume mapped such that data is persisted across container restarts (e.g., `docker run -v $(pwd):/data`)

| -| `DATABASE_DATA_DIR` | `$DATA_CACHE_DIR/db` |

The data directory for the default Postgres database.

| -| `DATABASE_URL` | `postgresql://postgres@ localhost:5432/sourcebot` |

Connection string of your Postgres database. By default, a Postgres database is automatically provisioned at startup within the container.

If you'd like to use a non-default schema, you can provide it as a parameter in the database url.

You can also use `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_NAME`, and `DATABASE_ARGS` to construct the database url.

| +| `DATABASE_URL` **(required)** | - |

Connection string of your Postgres database, e.g. `postgresql://user:password@host:5432/sourcebot`. As of v5, Sourcebot no longer ships an embedded Postgres database, so this must point at an external Postgres instance. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

If you'd like to use a non-default schema, you can provide it as a parameter in the database url.

You can also use `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_NAME`, and `DATABASE_ARGS` to construct the database url.

| | `EMAIL_FROM_ADDRESS` | `-` |

The email address that transactional emails will be sent from. See [this doc](/docs/configuration/transactional-emails) for more info.

| | `FORCE_ENABLE_ANONYMOUS_ACCESS` | `false` |

When enabled, [anonymous access](/docs/configuration/auth/access-settings#anonymous-access) to the organization will always be enabled

| `REQUIRE_APPROVAL_NEW_MEMBERS` | - |

When set, controls whether new users require approval before accessing your deployment. If not set, the setting can be configured via the UI. See [member approval](/docs/configuration/auth/access-settings#member-approval) for more info.

-| `REDIS_DATA_DIR` | `$DATA_CACHE_DIR/redis` |

The data directory for the default Redis instance.

| -| `REDIS_URL` | `redis://localhost:6379` |

Connection string of your Redis instance. By default, a Redis database is automatically provisioned at startup within the container.

To enable TLS, see [this doc](/docs/deployment/infrastructure/redis#tls).

| +| `REDIS_URL` **(required)** | - |

Connection string of your Redis instance, e.g. `redis://host:6379`. As of v5, Sourcebot no longer ships an embedded Redis instance, so this must point at an external Redis instance. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

To enable TLS, see [this doc](/docs/deployment/infrastructure/redis#tls).

| | `REDIS_REMOVE_ON_COMPLETE` | `0` |

Controls how many completed jobs are allowed to remain in Redis queues

| | `REDIS_REMOVE_ON_FAIL` | `100` |

Controls how many failed jobs are allowed to remain in Redis queues

| | `REPO_SYNC_RETRY_BASE_SLEEP_SECONDS` | `60` |

The base sleep duration (in seconds) for exponential backoff when retrying repository sync operations that fail

| diff --git a/docs/docs/upgrade/v4-to-v5-guide.mdx b/docs/docs/upgrade/v4-to-v5-guide.mdx index 527b1672c..fc55987aa 100644 --- a/docs/docs/upgrade/v4-to-v5-guide.mdx +++ b/docs/docs/upgrade/v4-to-v5-guide.mdx @@ -5,27 +5,114 @@ sidebarTitle: V4 to V5 guide This guide will walk you through upgrading your Sourcebot deployment from v4 to v5. - -Starting in v5, the following features require a paid plan: +## Breaking Changes + +### Ask Sourcebot & MCP Server relicensing + +**Who's affected:** Users without a paid Sourcebot subscription that use either [Ask Sourcebot](/docs/features/ask/ask-sourcebot) or the [MCP server](/docs/features/mcp-server). + + +Starting in v5, the following features have been relicensed from FSL to our [commercial license](https://github.com/sourcebot-dev/sourcebot/blob/main/ee/LICENSE), requiring a paid plan to use: - [Ask Sourcebot](/docs/features/ask/ask-sourcebot) - [MCP server](/docs/features/mcp-server) If your deployment uses these features and you upgrade to v5, you'll need to activate a paid plan to keep using them. All other features available on the free plan remain on the free plan. You can [start a 14-day free trial](/docs/free-trial) of the paid plan directly from your deployment. No credit card is required. + +### 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](/docs/deployment/docker-compose) and [Helm chart](https://github.com/sourcebot-dev/sourcebot-helm-chart) deployments are not affected, since both already provide their own Postgres and Redis. + + +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](/docs/deployment/docker-compose) or [Helm chart](https://github.com/sourcebot-dev/sourcebot-helm-chart) deployment, both of which wire these up for you. + + + +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. -There are no breaking changes between v4 and v5. Upgrading is as simple as pulling the latest image and restarting your deployment. +Redis only holds transient job-queue data, so there is nothing to migrate there. -# Staying on v4 +1. 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: -If you'd rather not upgrade to v5 or activate a paid plan, you can keep using v4 indefinitely by pinning your deployment to the final v4 release: +```bash wrap icon="terminal" +docker exec -t sourcebot pg_dump -U postgres -d sourcebot -Fc -f /tmp/sourcebot.dump +docker cp sourcebot:/tmp/sourcebot.dump ./sourcebot.dump +``` -```bash -ghcr.io/sourcebot-dev/sourcebot:v4.17.3 +2. Create the target database on your external Postgres instance (skip if it already exists): + +```bash wrap icon="terminal" +createdb -h your-postgres-host -p 5432 -U your-user sourcebot +``` + +3. Restore the dump into the external database: + +```bash wrap icon="terminal" +pg_restore -h your-postgres-host -p 5432 -U your-user -d sourcebot --no-owner ./sourcebot.dump +``` + +4. Set `DATABASE_URL` to point at the external database and start Sourcebot on v5. Sourcebot runs any outstanding schema migrations automatically at startup. + +```bash wrap icon="terminal" +docker run \ + -e DATABASE_URL='postgresql://your-user:your-password@your-postgres-host:5432/sourcebot' \ + -e REDIS_URL='redis://your-redis-host:6379' \ + # ... your other flags + ghcr.io/sourcebot-dev/sourcebot:latest +``` + + + +## Upgrading + + +Before upgrading, review the [Breaking Changes](#breaking-changes) section and complete any actions that apply to your deployment. + + +### Docker Compose + +1. Pull the latest image: + +```bash wrap icon="terminal" +docker compose pull ``` -v4 will continue to work as before, with Ask Sourcebot and MCP available for free. +2. Restart your deployment: + +```bash wrap icon="terminal" +docker compose up -d +``` + +### Helm chart + +1. Refresh the chart repository: + +```bash wrap icon="terminal" +helm repo update +``` + +2. Upgrade the release: + +```bash wrap icon="terminal" +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: + +```bash +ghcr.io/sourcebot-dev/sourcebot:v4.17.4 +``` ## Troubleshooting diff --git a/entrypoint.sh b/entrypoint.sh index dea1515b2..1e2c8465b 100644 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -47,20 +47,25 @@ if [ -z "$DATABASE_URL" ] && [ -n "$DATABASE_HOST" ] && [ -n "$DATABASE_USERNAME fi fi +# As of v5, Sourcebot no longer ships an embedded Postgres or Redis. Both must be +# provided externally via DATABASE_URL and REDIS_URL. +# @see: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide if [ -z "$DATABASE_URL" ]; then - echo -e "\e[34m[Info] DATABASE_URL is not set. Using embeded database.\e[0m" - export DATABASE_EMBEDDED="true" - export DATABASE_URL="postgresql://postgres@localhost:5432/sourcebot" -else - export DATABASE_EMBEDDED="false" + echo -e "\e[31m[Error] DATABASE_URL is not set.\e[0m" + echo -e "\e[31mAs of v5, Sourcebot no longer ships an embedded Postgres database. You must provide a\e[0m" + echo -e "\e[31mPostgres instance and set DATABASE_URL (e.g. postgresql://user:password@host:5432/sourcebot).\e[0m" + echo -e "\e[31mYou can also use DATABASE_HOST, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_NAME, and\e[0m" + echo -e "\e[31mDATABASE_ARGS to construct the connection string.\e[0m" + echo -e "\e[31mSee the migration guide: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide\e[0m" + exit 1 fi if [ -z "$REDIS_URL" ]; then - echo -e "\e[34m[Info] REDIS_URL is not set. Using embeded redis.\e[0m" - export REDIS_EMBEDDED="true" - export REDIS_URL="redis://localhost:6379" -else - export REDIS_EMBEDDED="false" + echo -e "\e[31m[Error] REDIS_URL is not set.\e[0m" + echo -e "\e[31mAs of v5, Sourcebot no longer ships an embedded Redis instance. You must provide a Redis\e[0m" + echo -e "\e[31minstance and set REDIS_URL (e.g. redis://host:6379).\e[0m" + echo -e "\e[31mSee the migration guide: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide\e[0m" + exit 1 fi # Extract version from version.ts @@ -98,23 +103,6 @@ if [ ! -d "$DATA_CACHE_DIR" ]; then mkdir -p "$DATA_CACHE_DIR" fi -# Check if DATABASE_DATA_DIR exists, if not initialize it -if [ "$DATABASE_EMBEDDED" = "true" ] && [ ! -d "$DATABASE_DATA_DIR" ]; then - echo -e "\e[34m[Info] Initializing database at $DATABASE_DATA_DIR...\e[0m" - mkdir -p $DATABASE_DATA_DIR - if [ "$IS_ROOT" = "true" ]; then - chown -R postgres:postgres "$DATABASE_DATA_DIR" - su postgres -c "initdb -D $DATABASE_DATA_DIR" - else - initdb -D "$DATABASE_DATA_DIR" -U postgres - fi -fi - -# Create the redis data directory if it doesn't exist -if [ "$REDIS_EMBEDDED" = "true" ] && [ ! -d "$REDIS_DATA_DIR" ]; then - mkdir -p $REDIS_DATA_DIR -fi - if [ -z "$SOURCEBOT_ENCRYPTION_KEY" ]; then echo -e "\e[33m[Warning] SOURCEBOT_ENCRYPTION_KEY is not set.\e[0m" @@ -201,43 +189,6 @@ fi echo "{\"version\": \"$SOURCEBOT_VERSION\", \"install_id\": \"$SOURCEBOT_INSTALL_ID\"}" > "$FIRST_RUN_FILE" -# Start the database and wait for it to be ready before starting any other service -if [ "$DATABASE_EMBEDDED" = "true" ]; then - if [ "$IS_ROOT" = "true" ]; then - su postgres -c "postgres -D $DATABASE_DATA_DIR" & - else - postgres -D "$DATABASE_DATA_DIR" & - fi - - until pg_isready -h localhost -p 5432 -U postgres; do - echo -e "\e[34m[Info] Waiting for the database to be ready...\e[0m" - sleep 1 - - # As postgres runs in the background, we must check if it is still - # running, otherwise the "until" loop will be running indefinitely. - if ! pgrep -x "postgres" > /dev/null; then - echo "postgres failed to run" - exit 1 - fi - done - - if [ "$IS_ROOT" = "false" ]; then - # Running as non-root we need to ensure the postgres account is created. - psql -U postgres -tc "SELECT 1 FROM pg_roles WHERE rolname='postgres'" | grep -q 1 \ - || createuser postgres -s - fi - - # Check if the database already exists, and create it if it doesn't exist - EXISTING_DB=$(psql -U postgres -tAc "SELECT 1 FROM pg_database WHERE datname = 'sourcebot'") - - if [ "$EXISTING_DB" = "1" ]; then - echo "Database 'sourcebot' already exists; skipping creation." - else - echo "Creating database 'sourcebot'..." - psql -U postgres -c "CREATE DATABASE \"sourcebot\"" - fi -fi - # Run a Database migration echo -e "\e[34m[Info] Running database migration...\e[0m" DATABASE_URL="$DATABASE_URL" yarn workspace @sourcebot/db prisma:migrate:prod diff --git a/supervisord.conf b/supervisord.conf index 19d308502..572136331 100644 --- a/supervisord.conf +++ b/supervisord.conf @@ -31,14 +31,4 @@ autorestart=true startretries=3 stdout_logfile=/dev/fd/1 stdout_logfile_maxbytes=0 -redirect_stderr=true - -[program:redis] -command=redis-server --dir %(ENV_REDIS_DATA_DIR)s -priority=10 -autostart=%(ENV_REDIS_EMBEDDED)s -autorestart=true -startretries=3 -stdout_logfile=/dev/fd/1 -stdout_logfile_maxbytes=0 redirect_stderr=true \ No newline at end of file From 076d9aaf862038e4abdedbe69f97977859791a5a Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 14:31:27 -0700 Subject: [PATCH 2/7] docs: point CHANGELOG entry at PR #1264 Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 774d9e693..c4644fb06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Redesigned the app layout with a new collapsible sidebar navigation, replacing the previous top navigation bar. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Expired offline license keys no longer crash the process. An expired key now degrades to the unlicensed state. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Improved the `setup-sourcebot` wizard: prompts for a setup directory, clarifies that secrets are stored locally in `.env`, switches multi-select to Tab, hides "No results" until a real search runs, and detects/cleans up conflicting Docker deployments and volumes before starting. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1264](https://github.com/sourcebot-dev/sourcebot/pull/1264) ### Fixed - Fixed git "dubious ownership" errors when the container runs as a non-root user by setting `safe.directory` at the system level instead of the global (root-only) level. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) From 5d5da07ad6bb986c0ec6e61eda128c118272d614 Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 14:31:57 -0700 Subject: [PATCH 3/7] changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c4644fb06..774d9e693 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Redesigned the app layout with a new collapsible sidebar navigation, replacing the previous top navigation bar. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Expired offline license keys no longer crash the process. An expired key now degrades to the unlicensed state. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Improved the `setup-sourcebot` wizard: prompts for a setup directory, clarifies that secrets are stored locally in `.env`, switches multi-select to Tab, hides "No results" until a real search runs, and detects/cleans up conflicting Docker deployments and volumes before starting. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1264](https://github.com/sourcebot-dev/sourcebot/pull/1264) +- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) ### Fixed - Fixed git "dubious ownership" errors when the container runs as a non-root user by setting `safe.directory` at the system level instead of the global (root-only) level. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) From 5d7a4d7beabb03e6d5c90c1168334df597b2a7bb Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 17:06:37 -0700 Subject: [PATCH 4/7] docs: expand v4-to-v5 guide; require AUTH_SECRET and SOURCEBOT_ENCRYPTION_KEY - entrypoint.sh: require AUTH_SECRET and SOURCEBOT_ENCRYPTION_KEY explicitly (no auto-generation, no plaintext file loading); hard-fail with migration guidance and warn if the legacy plaintext files linger - v4-to-v5 guide: document the secrets, role-management, and external Postgres/Redis breaking changes with per-item migration steps - environment-variables: mark both secrets required - roles-and-permissions: add default-role-by-plan table - CHANGELOG: update breaking-change entries Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 17 +-- .../auth/roles-and-permissions.mdx | 8 ++ .../configuration/environment-variables.mdx | 4 +- docs/docs/upgrade/v4-to-v5-guide.mdx | 128 ++++++++++++++++-- entrypoint.sh | 46 +++---- 5 files changed, 159 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 774d9e693..32067e4e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,20 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed +- [**Breaking Change**] Changed the default role assignment to `Owner` for organizations on the free tier. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- [**Breaking Change**] Relicensed Ask Sourcebot and MCP under ee. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- [**Breaking Change**] Sourcebot no longer auto-generates `AUTH_SECRET` and `SOURCEBOT_ENCRYPTION_KEY`, nor reads them from the plaintext files it previously wrote to the data volume; both must now be set explicitly as environment variables. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- Redesigned the app layout with a new collapsible sidebar navigation, replacing the previous top navigation bar. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- Expired offline license keys no longer crash the process. An expired key now degrades to the unlicensed state. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) +- Improved the `setup-sourcebot` wizard: prompts for a setup directory, clarifies that secrets are stored locally in `.env`, switches multi-select to Tab, hides "No results" until a real search runs, and detects/cleans up conflicting Docker deployments and volumes before starting. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) + ### Added - Added ask connectors: connect 3rd party MCP servers to your ask agent. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Added progress bar when navigating between pages. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Added a integrated changelog into the sidebar. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - Added scroll position restoration when viewing files in the code browser, so returning to a previously viewed file restores your scroll position. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -### Changed -- [**Breaking Change**] Changed the default role assignment to `Owner` for organizations on the free tier. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- [**Breaking Change**] Relicensed Ask Sourcebot and MCP under ee. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- Redesigned the app layout with a new collapsible sidebar navigation, replacing the previous top navigation bar. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- Expired offline license keys no longer crash the process. An expired key now degrades to the unlicensed state. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- Improved the `setup-sourcebot` wizard: prompts for a setup directory, clarifies that secrets are stored locally in `.env`, switches multi-select to Tab, hides "No results" until a real search runs, and detects/cleans up conflicting Docker deployments and volumes before starting. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) -- [**Breaking Change**] Removed the embedded Postgres and Redis from the Docker image. External Postgres and Redis are now required: set `DATABASE_URL` and `REDIS_URL`, or deploy with the provided `docker-compose.yml`. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - ### Fixed - Fixed git "dubious ownership" errors when the container runs as a non-root user by setting `safe.directory` at the system level instead of the global (root-only) level. [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) diff --git a/docs/docs/configuration/auth/roles-and-permissions.mdx b/docs/docs/configuration/auth/roles-and-permissions.mdx index 8840e2961..d9a625000 100644 --- a/docs/docs/configuration/auth/roles-and-permissions.mdx +++ b/docs/docs/configuration/auth/roles-and-permissions.mdx @@ -17,6 +17,14 @@ Note that when [permission syncing](/docs/features/permission-syncing) is enable On the free plan, all signed-in users are given the `Owner` role. +## Default role assignment + +When a user joins your organization, they are assigned a default role. This assignment, and the ability to [manage the user's role](#managing-member-roles) afterwards, depends on [your plan](/docs/activating-a-subscription): + +| Plan | Default role | Role management | +| :--- | :----------- | :-------------- | +| **Free** | `Owner` | Not available. A user's role cannot be changed. | +| **Paid** | `Member` | Available. Owners can [promote or demote](#managing-member-roles) members. | ## Managing member roles diff --git a/docs/docs/configuration/environment-variables.mdx b/docs/docs/configuration/environment-variables.mdx index bcaee8eed..a11d3b525 100644 --- a/docs/docs/configuration/environment-variables.mdx +++ b/docs/docs/configuration/environment-variables.mdx @@ -12,7 +12,7 @@ The following environment variables allow you to configure your Sourcebot deploy | :------- | :------ | :---------- | | `AUTH_CREDENTIALS_LOGIN_ENABLED` | `true` |

Enables/disables authentication with basic credentials. Username and passwords are stored encrypted at rest within the postgres database. Checkout the [auth docs](/docs/configuration/auth/authentication) for more info

| | `AUTH_EMAIL_CODE_LOGIN_ENABLED` | `false` |

Enables/disables authentication with a login code that's sent to a users email. `SMTP_CONNECTION_URL` and `EMAIL_FROM_ADDRESS` must also be set. Checkout the [auth docs](/docs/configuration/auth/authentication) for more info

| -| `AUTH_SECRET` | Automatically generated at startup if no value is provided. Generated using `openssl rand -base64 33` |

Used to validate login session cookies

| +| `AUTH_SECRET` **(required)** | - |

Used to validate login session cookies. As of v5, this must be set explicitly (generate one with `openssl rand -base64 33`). If you're upgrading from a version that auto-generated it, copy the value out of `$DATA_CACHE_DIR/.authjs-secret`, set it here, and delete that file. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

| | `AUTH_SESSION_MAX_AGE_SECONDS` | `2592000` (30 days) |

Relative time from now in seconds when to expire the session.

| | `AUTH_SESSION_UPDATE_AGE_SECONDS` | `86400` (1 day) |

How often the session should be updated in seconds. If set to `0`, session is updated every time.

| | `OAUTH_AUTHORIZATION_CODE_TTL_SECONDS` | `600` (10 minutes) |

Lifetime of an OAuth authorization code, in seconds.

| @@ -36,7 +36,7 @@ The following environment variables allow you to configure your Sourcebot deploy | `SMTP_PORT` | `-` |

The port of the SMTP server.

| | `SMTP_USERNAME` | `-` |

The username for SMTP authentication.

| | `SMTP_PASSWORD` | `-` |

The password for SMTP authentication.

| -| `SOURCEBOT_ENCRYPTION_KEY` | Automatically generated at startup if no value is provided. Generated using `openssl rand -base64 24` |

Used to encrypt connection secrets and generate API keys.

| +| `SOURCEBOT_ENCRYPTION_KEY` **(required)** | - |

Used to encrypt connection secrets and generate API keys. As of v5, this must be set explicitly (generate one with `openssl rand -base64 24`). If you're upgrading from a version that auto-generated it, copy the value out of `$DATA_CACHE_DIR/.secret`, set it here, and delete that file. Use the **same** key your data was encrypted with, otherwise existing connection secrets cannot be decrypted. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

| | `SOURCEBOT_PUBLIC_KEY_PATH` | `/app/public.pem` |

Sourcebot's public key that's used to verify encrypted license key signatures.

| | `SOURCEBOT_LOG_LEVEL` | `info` |

The Sourcebot logging level. Valid values are `debug`, `info`, `warn`, `error`, in order of severity.

| | `SOURCEBOT_STRUCTURED_LOGGING_ENABLED` | `false` |

Enables/disable structured JSON logging. See [this doc](/docs/configuration/structured-logging) for more info.

| diff --git a/docs/docs/upgrade/v4-to-v5-guide.mdx b/docs/docs/upgrade/v4-to-v5-guide.mdx index fc55987aa..57c1f3908 100644 --- a/docs/docs/upgrade/v4-to-v5-guide.mdx +++ b/docs/docs/upgrade/v4-to-v5-guide.mdx @@ -9,27 +9,62 @@ This guide will walk you through upgrading your Sourcebot deployment from v4 to ### Ask Sourcebot & MCP Server relicensing -**Who's affected:** Users without a paid Sourcebot subscription that use either [Ask Sourcebot](/docs/features/ask/ask-sourcebot) or the [MCP server](/docs/features/mcp-server). +**Who's affected:** Users on the [free plan](/docs/activating-a-subscription). +#### Description Starting in v5, the following features have been relicensed from FSL to our [commercial license](https://github.com/sourcebot-dev/sourcebot/blob/main/ee/LICENSE), requiring a paid plan to use: - [Ask Sourcebot](/docs/features/ask/ask-sourcebot) - [MCP server](/docs/features/mcp-server) If your deployment uses these features and you upgrade to v5, you'll need to activate a paid plan to keep using them. All other features available on the free plan remain on the free plan. -You can [start a 14-day free trial](/docs/free-trial) of the paid plan directly from your deployment. No credit card is required. +#### Action Items + +You can [start a 14-day free trial](/docs/free-trial) of the paid plan directly from your deployment. No credit card is required. See the [pricing page](https://sourcebot.dev/pricing) for more details. + +Alternatively, you can choose to [stay on v4](#staying-on-v4). + + +### User role management relicensing + +**Who's affected:** Users on the [free plan](/docs/activating-a-subscription). + + +#### Description + +[Managing user roles](/docs/configuration/auth/roles-and-permissions) 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](/docs/configuration/auth/roles-and-permissions#managing-member-roles) 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](#managing-member-roles) 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](/docs/free-trial) of the paid plan directly from your deployment. No credit card is required. See the [pricing page](https://sourcebot.dev/pricing) for more details. + +Alternatively, you can choose to [stay on v4](#staying-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](/docs/deployment/docker-compose) and [Helm chart](https://github.com/sourcebot-dev/sourcebot-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](/docs/deployment/docker-compose) or [Helm chart](https://github.com/sourcebot-dev/sourcebot-helm-chart) deployment, both of which wire these up for you. - +#### Action Items + + +
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. @@ -37,8 +72,6 @@ The embedded Postgres stored its data under `$DATA_CACHE_DIR/db` inside the cont 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. -Redis only holds transient job-queue data, so there is nothing to migrate there. - 1. 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: ```bash wrap icon="terminal" @@ -46,29 +79,102 @@ docker exec -t sourcebot pg_dump -U postgres -d sourcebot -Fc -f /tmp/sourcebot. docker cp sourcebot:/tmp/sourcebot.dump ./sourcebot.dump ``` -2. Create the target database on your external Postgres instance (skip if it already exists): +2. 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](https://github.com/sourcebot-dev/sourcebot/blob/main/docker-compose.yml), or the one provided by the [Helm chart](https://github.com/sourcebot-dev/sourcebot-helm-chart). Make sure it's reachable from where Sourcebot runs. + +3. **(Optional)** When using a database other than `postgres`, you need to create it: + ```bash wrap icon="terminal" -createdb -h your-postgres-host -p 5432 -U your-user sourcebot +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. + -3. Restore the dump into the external database: +4. Restore the dump into the database: ```bash wrap icon="terminal" -pg_restore -h your-postgres-host -p 5432 -U your-user -d sourcebot --no-owner ./sourcebot.dump +pg_restore -U postgres -d postgres --no-owner ./sourcebot.dump ``` -4. Set `DATABASE_URL` to point at the external database and start Sourcebot on v5. Sourcebot runs any outstanding schema migrations automatically at startup. +5. Set `DATABASE_URL` to point at the external database and start Sourcebot on v5. Sourcebot runs any outstanding schema migrations automatically at startup. + +```bash wrap icon="terminal" +docker run \ + -e DATABASE_URL='postgresql://your-user:your-password@your-postgres-host:5432/postgres' \ + # ... your other flags + ghcr.io/sourcebot-dev/sourcebot:latest +``` + + + +
+ +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. + +1. 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](https://github.com/sourcebot-dev/sourcebot/blob/main/docker-compose.yml), or the one provided by the [Helm chart](https://github.com/sourcebot-dev/sourcebot-helm-chart). Make sure it's reachable from where Sourcebot runs. + +2. Set `REDIS_URL` to point at it when you start Sourcebot on v5: ```bash wrap icon="terminal" docker run \ - -e DATABASE_URL='postgresql://your-user:your-password@your-postgres-host:5432/sourcebot' \ -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](/docs/deployment/docker-compose) and [Helm chart](https://github.com/sourcebot-dev/sourcebot-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 + + + +
+ +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`. + +1. With your **v4** deployment still running, print the stored values. Replace `sourcebot` with your container name if it differs: + +```bash wrap icon="terminal" +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. + +2. Set both as environment variables on your v5 deployment: + +```bash wrap icon="terminal" +docker run \ + -e SOURCEBOT_ENCRYPTION_KEY='' \ + -e AUTH_SECRET='' \ + # ... your other flags + ghcr.io/sourcebot-dev/sourcebot:latest +``` + +3. Delete the plaintext files from the data volume so the secrets are no longer stored on disk: + +```bash wrap icon="terminal" +docker exec sourcebot rm /data/.sourcebot/.secret /data/.sourcebot/.authjs-secret +``` + +Sourcebot warns at startup if either file is still present. + + ## Upgrading diff --git a/entrypoint.sh b/entrypoint.sh index 1e2c8465b..7c3654e6a 100644 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -47,8 +47,7 @@ if [ -z "$DATABASE_URL" ] && [ -n "$DATABASE_HOST" ] && [ -n "$DATABASE_USERNAME fi fi -# As of v5, Sourcebot no longer ships an embedded Postgres or Redis. Both must be -# provided externally via DATABASE_URL and REDIS_URL. +# As of v5, Sourcebot no longer ships an embedded Postgres. # @see: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide if [ -z "$DATABASE_URL" ]; then echo -e "\e[31m[Error] DATABASE_URL is not set.\e[0m" @@ -60,6 +59,8 @@ if [ -z "$DATABASE_URL" ]; then exit 1 fi +# As of v5, Sourcebot no longer ships an embedded Redis. +# @see: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide if [ -z "$REDIS_URL" ]; then echo -e "\e[31m[Error] REDIS_URL is not set.\e[0m" echo -e "\e[31mAs of v5, Sourcebot no longer ships an embedded Redis instance. You must provide a Redis\e[0m" @@ -103,37 +104,36 @@ if [ ! -d "$DATA_CACHE_DIR" ]; then mkdir -p "$DATA_CACHE_DIR" fi +# As of v5, SOURCEBOT_ENCRYPTION_KEY must be provided explicitly via an environment variable. +# @see: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide if [ -z "$SOURCEBOT_ENCRYPTION_KEY" ]; then - echo -e "\e[33m[Warning] SOURCEBOT_ENCRYPTION_KEY is not set.\e[0m" - + echo -e "\e[31m[Error] SOURCEBOT_ENCRYPTION_KEY is not set.\e[0m" if [ -f "$DATA_CACHE_DIR/.secret" ]; then - echo -e "\e[34m[Info] Loading environment variables from $DATA_CACHE_DIR/.secret\e[0m" + echo -e "\e[31mA key generated by an earlier version of Sourcebot was found at $DATA_CACHE_DIR/.secret.\e[0m" + echo -e "\e[31mCopy its value into the SOURCEBOT_ENCRYPTION_KEY environment variable, then delete the file.\e[0m" else - echo -e "\e[34m[Info] Generating a new encryption key...\e[0m" - SOURCEBOT_ENCRYPTION_KEY=$(openssl rand -base64 24) - echo "SOURCEBOT_ENCRYPTION_KEY=\"$SOURCEBOT_ENCRYPTION_KEY\"" >> "$DATA_CACHE_DIR/.secret" + echo -e "\e[31mGenerate one with 'openssl rand -base64 24' and set it as the SOURCEBOT_ENCRYPTION_KEY environment variable.\e[0m" fi - - set -a - . "$DATA_CACHE_DIR/.secret" - set +a + echo -e "\e[31mSee the migration guide: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide\e[0m" + exit 1 +elif [ -f "$DATA_CACHE_DIR/.secret" ]; then + echo -e "\e[33m[Warning] $DATA_CACHE_DIR/.secret is no longer used and stores the encryption key in plain text. Delete it.\e[0m" fi -# @see : https://authjs.dev/getting-started/deployment#auth_secret +# As of v5, AUTH_SECRET must be provided explicitly via an environment variable. +# @see: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide if [ -z "$AUTH_SECRET" ]; then - echo -e "\e[33m[Warning] AUTH_SECRET is not set.\e[0m" - + echo -e "\e[31m[Error] AUTH_SECRET is not set.\e[0m" if [ -f "$DATA_CACHE_DIR/.authjs-secret" ]; then - echo -e "\e[34m[Info] Loading environment variables from $DATA_CACHE_DIR/.authjs-secret\e[0m" + echo -e "\e[31mA secret generated by an earlier version of Sourcebot was found at $DATA_CACHE_DIR/.authjs-secret.\e[0m" + echo -e "\e[31mCopy its value into the AUTH_SECRET environment variable, then delete the file.\e[0m" else - echo -e "\e[34m[Info] Generating a new encryption key...\e[0m" - AUTH_SECRET=$(openssl rand -base64 33) - echo "AUTH_SECRET=\"$AUTH_SECRET\"" >> "$DATA_CACHE_DIR/.authjs-secret" + echo -e "\e[31mGenerate one with 'openssl rand -base64 33' and set it as the AUTH_SECRET environment variable.\e[0m" fi - - set -a - . "$DATA_CACHE_DIR/.authjs-secret" - set +a + echo -e "\e[31mSee the migration guide: https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide\e[0m" + exit 1 +elif [ -f "$DATA_CACHE_DIR/.authjs-secret" ]; then + echo -e "\e[33m[Warning] $DATA_CACHE_DIR/.authjs-secret is no longer used and stores the secret in plain text. Delete it.\e[0m" fi if [ -z "$AUTH_URL" ]; then From 8a3a949a606b855b27d9ecd0419f300f1c72a388 Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 17:13:34 -0700 Subject: [PATCH 5/7] docs nit --- docs/docs/configuration/environment-variables.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/configuration/environment-variables.mdx b/docs/docs/configuration/environment-variables.mdx index a11d3b525..8c0415fc4 100644 --- a/docs/docs/configuration/environment-variables.mdx +++ b/docs/docs/configuration/environment-variables.mdx @@ -12,7 +12,7 @@ The following environment variables allow you to configure your Sourcebot deploy | :------- | :------ | :---------- | | `AUTH_CREDENTIALS_LOGIN_ENABLED` | `true` |

Enables/disables authentication with basic credentials. Username and passwords are stored encrypted at rest within the postgres database. Checkout the [auth docs](/docs/configuration/auth/authentication) for more info

| | `AUTH_EMAIL_CODE_LOGIN_ENABLED` | `false` |

Enables/disables authentication with a login code that's sent to a users email. `SMTP_CONNECTION_URL` and `EMAIL_FROM_ADDRESS` must also be set. Checkout the [auth docs](/docs/configuration/auth/authentication) for more info

| -| `AUTH_SECRET` **(required)** | - |

Used to validate login session cookies. As of v5, this must be set explicitly (generate one with `openssl rand -base64 33`). If you're upgrading from a version that auto-generated it, copy the value out of `$DATA_CACHE_DIR/.authjs-secret`, set it here, and delete that file. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

| +| `AUTH_SECRET` **(required)** | - |

Used to validate login session cookies. Genearte one with `openssl rand -base64 33`.

| | `AUTH_SESSION_MAX_AGE_SECONDS` | `2592000` (30 days) |

Relative time from now in seconds when to expire the session.

| | `AUTH_SESSION_UPDATE_AGE_SECONDS` | `86400` (1 day) |

How often the session should be updated in seconds. If set to `0`, session is updated every time.

| | `OAUTH_AUTHORIZATION_CODE_TTL_SECONDS` | `600` (10 minutes) |

Lifetime of an OAuth authorization code, in seconds.

| @@ -22,11 +22,11 @@ The following environment variables allow you to configure your Sourcebot deploy | `CONFIG_PATH` | `-` |

The container relative path to the declarative configuration file. See [this doc](/docs/configuration/declarative-config) for more info.

| | `DATA_CACHE_DIR` | `$DATA_DIR/.sourcebot` |

The root data directory in which all data written to disk by Sourcebot will be located.

| | `DATA_DIR` | `/data` |

The directory within the container to store all persistent data. Typically, this directory will be volume mapped such that data is persisted across container restarts (e.g., `docker run -v $(pwd):/data`)

| -| `DATABASE_URL` **(required)** | - |

Connection string of your Postgres database, e.g. `postgresql://user:password@host:5432/sourcebot`. As of v5, Sourcebot no longer ships an embedded Postgres database, so this must point at an external Postgres instance. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

If you'd like to use a non-default schema, you can provide it as a parameter in the database url.

You can also use `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_NAME`, and `DATABASE_ARGS` to construct the database url.

| +| `DATABASE_URL` **(required)** | - |

Connection string of your Postgres database, e.g. `postgresql://user:password@host:5432/sourcebot`.

If you'd like to use a non-default schema, you can provide it as a parameter in the database url.

You can also use `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_NAME`, and `DATABASE_ARGS` to construct the database url.

| | `EMAIL_FROM_ADDRESS` | `-` |

The email address that transactional emails will be sent from. See [this doc](/docs/configuration/transactional-emails) for more info.

| | `FORCE_ENABLE_ANONYMOUS_ACCESS` | `false` |

When enabled, [anonymous access](/docs/configuration/auth/access-settings#anonymous-access) to the organization will always be enabled

| `REQUIRE_APPROVAL_NEW_MEMBERS` | - |

When set, controls whether new users require approval before accessing your deployment. If not set, the setting can be configured via the UI. See [member approval](/docs/configuration/auth/access-settings#member-approval) for more info.

-| `REDIS_URL` **(required)** | - |

Connection string of your Redis instance, e.g. `redis://host:6379`. As of v5, Sourcebot no longer ships an embedded Redis instance, so this must point at an external Redis instance. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

To enable TLS, see [this doc](/docs/deployment/infrastructure/redis#tls).

| +| `REDIS_URL` **(required)** | - |

Connection string of your Redis instance, e.g. `redis://host:6379`.

To enable TLS, see [this doc](/docs/deployment/infrastructure/redis#tls).

| | `REDIS_REMOVE_ON_COMPLETE` | `0` |

Controls how many completed jobs are allowed to remain in Redis queues

| | `REDIS_REMOVE_ON_FAIL` | `100` |

Controls how many failed jobs are allowed to remain in Redis queues

| | `REPO_SYNC_RETRY_BASE_SLEEP_SECONDS` | `60` |

The base sleep duration (in seconds) for exponential backoff when retrying repository sync operations that fail

| @@ -36,7 +36,7 @@ The following environment variables allow you to configure your Sourcebot deploy | `SMTP_PORT` | `-` |

The port of the SMTP server.

| | `SMTP_USERNAME` | `-` |

The username for SMTP authentication.

| | `SMTP_PASSWORD` | `-` |

The password for SMTP authentication.

| -| `SOURCEBOT_ENCRYPTION_KEY` **(required)** | - |

Used to encrypt connection secrets and generate API keys. As of v5, this must be set explicitly (generate one with `openssl rand -base64 24`). If you're upgrading from a version that auto-generated it, copy the value out of `$DATA_CACHE_DIR/.secret`, set it here, and delete that file. Use the **same** key your data was encrypted with, otherwise existing connection secrets cannot be decrypted. See the [v4 to v5 guide](/docs/upgrade/v4-to-v5-guide).

| +| `SOURCEBOT_ENCRYPTION_KEY` **(required)** | - |

Used to encrypt connection secrets and generate API keys. Generate one with `openssl rand -base64 24`.

| | `SOURCEBOT_PUBLIC_KEY_PATH` | `/app/public.pem` |

Sourcebot's public key that's used to verify encrypted license key signatures.

| | `SOURCEBOT_LOG_LEVEL` | `info` |

The Sourcebot logging level. Valid values are `debug`, `info`, `warn`, `error`, in order of severity.

| | `SOURCEBOT_STRUCTURED_LOGGING_ENABLED` | `false` |

Enables/disable structured JSON logging. See [this doc](/docs/configuration/structured-logging) for more info.

| From 7e12eca8d3777a97106f5881b6bd7f9e7ce72c5f Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 17:15:27 -0700 Subject: [PATCH 6/7] changelog nit --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32067e4e3..f70b1a064 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +Checkout the [migration guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide) for details on upgrading your instance to v5. + ### Changed - [**Breaking Change**] Changed the default role assignment to `Owner` for organizations on the free tier. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) - [**Breaking Change**] Relicensed Ask Sourcebot and MCP under ee. See the [v4 to v5 guide](https://docs.sourcebot.dev/docs/upgrade/v4-to-v5-guide). [#1106](https://github.com/sourcebot-dev/sourcebot/pull/1106) From 33cb8495a5853df524c0bca882539a39d3ec53f2 Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Tue, 2 Jun 2026 17:33:27 -0700 Subject: [PATCH 7/7] final nits --- docs/docs/upgrade/v4-to-v5-guide.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/docs/upgrade/v4-to-v5-guide.mdx b/docs/docs/upgrade/v4-to-v5-guide.mdx index 57c1f3908..a392326d9 100644 --- a/docs/docs/upgrade/v4-to-v5-guide.mdx +++ b/docs/docs/upgrade/v4-to-v5-guide.mdx @@ -16,8 +16,9 @@ This guide will walk you through upgrading your Sourcebot deployment from v4 to Starting in v5, the following features have been relicensed from FSL to our [commercial license](https://github.com/sourcebot-dev/sourcebot/blob/main/ee/LICENSE), requiring a paid plan to use: - [Ask Sourcebot](/docs/features/ask/ask-sourcebot) - [MCP server](/docs/features/mcp-server) +- [User role management](/docs/configuration/auth/roles-and-permissions#managing-member-roles) ([details](#user-role-management-relicensing)) -If your deployment uses these features and you upgrade to v5, you'll need to activate a paid plan to keep using them. All other features available on the free plan remain on the free plan. +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 @@ -184,13 +185,13 @@ Before upgrading, review the [Breaking Changes](#breaking-changes) section and c ### Docker Compose -1. Pull the latest image: +1. Pull the latest image ```bash wrap icon="terminal" docker compose pull ``` -2. Restart your deployment: +2. Restart your deployment ```bash wrap icon="terminal" docker compose up -d @@ -198,13 +199,13 @@ docker compose up -d ### Helm chart -1. Refresh the chart repository: +1. Refresh the chart repository ```bash wrap icon="terminal" helm repo update ``` -2. Upgrade the release: +2. Upgrade the release ```bash wrap icon="terminal" helm upgrade sourcebot sourcebot/sourcebot \