Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

fix(platform): generate secrets in the Compose installer and add an upgrade path (#14712)

Krzysztof Czerwinskief3c9c6967f2
diff --git a/autogpt_platform/backend/backend/cli/main.py b/autogpt_platform/backend/backend/cli/main.py
index b049393c0c..f190466948 100644
--- a/autogpt_platform/backend/backend/cli/main.py
+++ b/autogpt_platform/backend/backend/cli/main.py
@@ -9,6 +9,7 @@ import psutil
from backend.util.process import AppProcess
from .chat import chat
+from .rotate_key import rotate_encryption_key
from .store import store
from .test import test
@@ -20,6 +21,7 @@ def main():
main.add_command(chat)
+main.add_command(rotate_encryption_key)
main.add_command(store)
main.add_command(test)
diff --git a/autogpt_platform/backend/backend/cli/rotate_key.py b/autogpt_platform/backend/backend/cli/rotate_key.py
new file mode 100644
index 0000000000..003aebf1f2
--- /dev/null
+++ b/autogpt_platform/backend/backend/cli/rotate_key.py
@@ -0,0 +1,130 @@
+import click
+
+
[email protected](name="rotate-encryption-key")
+ "--old-key",
+ envvar="OLD_ENCRYPTION_KEY",
+ required=True,
+ help="The ENCRYPTION_KEY the data was written under. "
+ "Also read from OLD_ENCRYPTION_KEY.",
+)
[email protected]("--apply", is_flag=True, help="Write the results. Without it, dry run.")
+def rotate_encryption_key(old_key: str, apply: bool):
+ """Re-encrypt stored credentials under the configured ENCRYPTION_KEY.
+
+ Run it with the stack stopped, after changing ENCRYPTION_KEY: everything
+ written under --old-key is decrypted and written back under the new key,
+ so connected integrations keep working. Idempotent: a value already
+ readable with the new key is never touched, and one that neither key can
+ read is reported and left as it is.
+ """
+ import asyncio
+
+ asyncio.run(_run_rotation(old_key=old_key, apply=apply))
+
+
+async def _run_rotation(*, old_key: str, apply: bool) -> None:
+ import prisma.models
+ from cryptography.fernet import Fernet, InvalidToken, MultiFernet
+
+ from backend.data.db import connect, disconnect
+ from backend.util.settings import Settings
+
+ new_key = Settings().secrets.encryption_key
+ if not new_key:
+ raise click.ClickException(
+ "ENCRYPTION_KEY is not set, so there is no key to re-encrypt under."
+ )
+ if new_key == old_key:
+ raise click.ClickException(
+ "--old-key is the configured ENCRYPTION_KEY. Change ENCRYPTION_KEY "
+ "first, then pass the previous value here."
+ )
+ try:
+ new, old = Fernet(new_key.encode()), Fernet(old_key.encode())
+ except ValueError as e:
+ raise click.ClickException(f"Not a valid encryption key: {e}")
+ rotator = MultiFernet([new, old])
+
+ def reencrypt(token: str) -> str | None:
+ """The token under the new key, None if it is already there."""
+ try:
+ new.decrypt(token.encode())
+ return None
+ except InvalidToken:
+ return rotator.rotate(token.encode()).decode()
+
+ async def user_tokens():
+ rows = await prisma.models.User.prisma().find_many(
+ where={"integrations": {"not": ""}}
+ )
+ return [(row.id, row.integrations) for row in rows]
+
+ async def credential_tokens():
+ rows = await prisma.models.IntegrationCredential.prisma().find_many()
+ return [(row.id, row.encryptedPayload) for row in rows]
+
+ async def bot_install_tokens():
+ rows = await prisma.models.BotInstall.prisma().find_many()
+ return [(row.id, row.credentials) for row in rows]
+
+ async def write_user(id: str, token: str):
+ await prisma.models.User.prisma().update(
+ where={"id": id}, data={"integrations": token}
+ )
+
+ async def write_credential(id: str, token: str):
+ await prisma.models.IntegrationCredential.prisma().update(
+ where={"id": id}, data={"encryptedPayload": token}
+ )
+
+ async def write_bot_install(id: str, token: str):
+ await prisma.models.BotInstall.prisma().update(
+ where={"id": id}, data={"credentials": token}
+ )
+
+ targets = [
+ ("User.integrations", user_tokens, write_user),
+ ("IntegrationCredential.encryptedPayload", credential_tokens, write_credential),
+ ("BotInstall.credentials", bot_install_tokens, write_bot_install),
+ ]
+
+ await connect()
+ try:
+ print(
+ "Re-encrypting stored credentials"
+ + ("" if apply else " (dry run — nothing will be written)")
+ )
+ unreadable = 0
+ for label, read, write in targets:
+ rotated = current = failed = 0
+ for id, stored in await read():
+ if not stored:
+ continue
+ try:
+ token = reencrypt(stored)
+ except InvalidToken:
+ failed += 1
+ print(f" {label} {id}: neither key can read it, left as is")
+ continue
+ if token is None:
+ current += 1
+ continue
+ rotated += 1
+ if apply:
+ await write(id, token)
+ unreadable += failed
+ print(
+ f"{label}: {rotated} {'re-encrypted' if apply else 'to re-encrypt'}, "
+ f"{current} already on the new key, {failed} unreadable"
+ )
+ if unreadable:
+ print(
+ f"{unreadable} value(s) were written under some other key. "
+ "Re-run with that key as --old-key, or reconnect those integrations."
+ )
+ if not apply:
+ print("Re-run with --apply to write the changes.")
+ finally:
+ await disconnect()
diff --git a/autogpt_platform/backend/backend/cli/rotate_key_test.py b/autogpt_platform/backend/backend/cli/rotate_key_test.py
new file mode 100644
index 0000000000..c5be82f573
--- /dev/null
+++ b/autogpt_platform/backend/backend/cli/rotate_key_test.py
@@ -0,0 +1,153 @@
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import click
+import pytest
+from cryptography.fernet import Fernet
+
+from backend.cli.rotate_key import _run_rotation
+
+OLD_KEY = Fernet.generate_key().decode()
+NEW_KEY = Fernet.generate_key().decode()
+
+
+def _encrypted(key: str, data: dict) -> str:
+ return Fernet(key.encode()).encrypt(json.dumps(data).encode()).decode()
+
+
+def _decrypted(key: str, token: str) -> dict:
+ return json.loads(Fernet(key.encode()).decrypt(token.encode()))
+
+
+def rotation(monkeypatch):
+ """Drive _run_rotation against in-memory rows, recording every write."""
+ import prisma.models
+
+ from backend.data import db as data_db
+ from backend.util import settings
+
+ monkeypatch.setattr(data_db, "connect", AsyncMock())
+ monkeypatch.setattr(data_db, "disconnect", AsyncMock())
+
+ state = SimpleNamespace(
+ new_key=NEW_KEY, users=[], credentials=[], bot_installs=[], writes=[]
+ )
+ monkeypatch.setattr(
+ settings,
+ "Settings",
+ lambda: SimpleNamespace(secrets=SimpleNamespace(encryption_key=state.new_key)),
+ )
+
+ def client(rows: str):
+ mock = MagicMock()
+ mock.find_many = AsyncMock(side_effect=lambda **_: getattr(state, rows))
+ mock.update = AsyncMock(
+ side_effect=lambda where, data: state.writes.append((where["id"], data))
+ )
+ return MagicMock(return_value=mock)
+
+ monkeypatch.setattr(prisma.models.User, "prisma", client("users"))
+ monkeypatch.setattr(
+ prisma.models.IntegrationCredential, "prisma", client("credentials")
+ )
+ monkeypatch.setattr(prisma.models.BotInstall, "prisma", client("bot_installs"))
+ return state
+
+
+async def test_every_store_is_readable_under_the_new_key_afterwards(rotation):
+ rotation.users = [
+ SimpleNamespace(id="u1", integrations=_encrypted(OLD_KEY, {"a": 1}))
+ ]
+ rotation.credentials = [
+ SimpleNamespace(id="c1", encryptedPayload=_encrypted(OLD_KEY, {"b": 2}))
+ ]
+ rotation.bot_installs = [
+ SimpleNamespace(id="b1", credentials=_encrypted(OLD_KEY, {"bot_token": "t"}))
+ ]
+
+ await _run_rotation(old_key=OLD_KEY, apply=True)
+
+ written = {id: data for id, data in rotation.writes}
+ assert _decrypted(NEW_KEY, written["u1"]["integrations"]) == {"a": 1}
+ assert _decrypted(NEW_KEY, written["c1"]["encryptedPayload"]) == {"b": 2}
+ assert _decrypted(NEW_KEY, written["b1"]["credentials"]) == {"bot_token": "t"}
+
+
+async def test_a_dry_run_writes_nothing(rotation, capsys):
+ rotation.credentials = [
+ SimpleNamespace(id="c1", encryptedPayload=_encrypted(OLD_KEY, {"b": 2}))
+ ]
+
+ await _run_rotation(old_key=OLD_KEY, apply=False)
+
+ assert rotation.writes == []
+ assert "1 to re-encrypt" in capsys.readouterr().out
+
+
+async def test_a_dry_run_with_unreadable_values_still_offers_apply(rotation, capsys):
+ rotation.credentials = [
+ SimpleNamespace(
+ id="c1",
+ encryptedPayload=_encrypted(Fernet.generate_key().decode(), {"b": 2}),
+ ),
+ SimpleNamespace(id="c2", encryptedPayload=_encrypted(OLD_KEY, {"c": 3})),
+ ]
+
+ await _run_rotation(old_key=OLD_KEY, apply=False)
+
+ out = capsys.readouterr().out
+ assert "written under some other key" in out
+ assert "Re-run with --apply" in out
+
+
+async def test_a_value_already_on_the_new_key_is_left_alone(rotation):
+ rotation.credentials = [
+ SimpleNamespace(id="c1", encryptedPayload=_encrypted(NEW_KEY, {"b": 2}))
+ ]
+
+ await _run_rotation(old_key=OLD_KEY, apply=True)
+
+ assert rotation.writes == []
+
+
+async def test_a_value_neither_key_reads_is_reported_and_left_alone(rotation, capsys):
+ other_key = Fernet.generate_key().decode()
+ rotation.users = [SimpleNamespace(id="u0", integrations="")]
+ rotation.credentials = [
+ SimpleNamespace(id="c1", encryptedPayload=_encrypted(other_key, {"b": 2})),
+ SimpleNamespace(id="c2", encryptedPayload=_encrypted(OLD_KEY, {"c": 3})),
+ ]
+
+ await _run_rotation(old_key=OLD_KEY, apply=True)
+
+ assert [id for id, _ in rotation.writes] == ["c2"]
+ out = capsys.readouterr().out
+ assert "c1: neither key can read it" in out
+ assert (
+ "User.integrations: 0 re-encrypted, 0 already on the new key, 0 unreadable"
+ ) in out
+ assert (
+ "IntegrationCredential.encryptedPayload: 1 re-encrypted, "
+ "0 already on the new key, 1 unreadable"
+ ) in out
+
+
+ "new_key, old_key, message",
+ [
+ ("", OLD_KEY, "ENCRYPTION_KEY is not set"),
+ (OLD_KEY, OLD_KEY, "Change ENCRYPTION_KEY first"),
+ (NEW_KEY, "not-a-fernet-key", "Not a valid encryption key"),
+ ],
+)
+async def test_unusable_keys_stop_before_touching_the_database(
+ rotation, new_key, old_key, message
+):
+ rotation.new_key = new_key
+
+ with pytest.raises(click.ClickException, match=message):
+ await _run_rotation(old_key=old_key, apply=True)
+
+ assert rotation.writes == []
diff --git a/autogpt_platform/backend/backend/util/secrets_guard.py b/autogpt_platform/backend/backend/util/secrets_guard.py
index e760b6535b..b5444d743a 100644
--- a/autogpt_platform/backend/backend/util/secrets_guard.py
+++ b/autogpt_platform/backend/backend/util/secrets_guard.py
@@ -24,6 +24,11 @@ MISSING_HINT = (
"file if needed) and run `make init-env` in autogpt_platform/ to generate a "
"value for it. Values you already set are never overwritten."
)
+UPGRADE_HINT = (
+ " Upgrading an install that already has connected integrations? They can be "
+ "moved to the new key instead of reconnected: see 'Upgrading: secrets are "
+ "generated per install' in docs/platform/getting-started.md."
+)
RETIRED_HINT = (
"Clear the value in autogpt_platform/backend/.env (leave `{name}=`) and run "
"`make init-env` in autogpt_platform/ to generate a fresh one."
@@ -53,7 +58,7 @@ def check_secrets(settings: Settings | None = None) -> None:
raise ValueError(
"ENCRYPTION_KEY is not set. It encrypts stored integration "
"credentials and signs cached values, so the backend will not "
- f"start without it. {MISSING_HINT}"
+ f"start without it. {MISSING_HINT}{UPGRADE_HINT}"
)
for name, value in configured.items():
@@ -61,12 +66,7 @@ def check_secrets(settings: Settings | None = None) -> None:
_RETIRED_DIGESTS[name]
):
continue
- rotation_note = (
- " Credentials stored under the old key become unreadable, so those "
- "integrations need reconnecting."
- if name == "ENCRYPTION_KEY"
- else ""
- )
+ rotation_note = UPGRADE_HINT if name == "ENCRYPTION_KEY" else ""
raise ValueError(
f"{name} is set to a value that was published in this repository's "
"public .env.default and must be treated as compromised. "
diff --git a/autogpt_platform/backend/backend/util/secrets_guard_test.py b/autogpt_platform/backend/backend/util/secrets_guard_test.py
index d411bdec43..d090acbd0a 100644
--- a/autogpt_platform/backend/backend/util/secrets_guard_test.py
+++ b/autogpt_platform/backend/backend/util/secrets_guard_test.py
@@ -70,3 +70,16 @@ def test_guard_covers_every_secret_that_env_default_used_to_ship():
for digests in secrets_guard._RETIRED_DIGESTS.values():
assert digests, "a name with no digests silently disables the guard"
assert all(len(digest) == 64 for digest in digests)
+
+
+def test_encryption_key_errors_point_at_the_upgrade_path(monkeypatch):
+ published = "pretend-this-was-shipped-in-env-default"
+ monkeypatch.setitem(
+ secrets_guard._RETIRED_DIGESTS,
+ "ENCRYPTION_KEY",
+ {hashlib.sha256(published.encode()).hexdigest()},
+ )
+
+ for encryption_key in ("", published):
+ with pytest.raises(ValueError, match="Upgrading: secrets are generated"):
+ check_secrets(_settings(encryption_key))
diff --git a/autogpt_platform/installer/setup-autogpt.bat b/autogpt_platform/installer/setup-autogpt.bat
index 2ecc6a6377..aca1739867 100644
--- a/autogpt_platform/installer/setup-autogpt.bat
+++ b/autogpt_platform/installer/setup-autogpt.bat
@@ -142,6 +142,9 @@ if "%CLONE_NEEDED%"=="1" (
)
echo.
+REM --- Generate the secrets the .env.default files leave blank ---
+call :init_env || exit /b 1
+
REM --- Bootstrap Ollama (optional) ---
if "%WITH_OLLAMA%"=="1" (
call :bootstrap_ollama || exit /b 1
@@ -175,6 +178,32 @@ if errorlevel 1 (
exit /b 1
)
+REM `up -d` succeeds as soon as the containers are created, so a backend
+REM that exits on startup would otherwise be reported as a working install.
+REM Wait for it to answer rather than for a fixed time: on a slow host the
+REM imports alone can take longer than any short window.
+echo Waiting for the backend to come up...
+set BACKEND_TRIES=0
+:backend_wait
+timeout /t 5 /nobreak >nul
+docker compose ps --status exited --services 2>nul | findstr /x /c:"rest_server" >nul
+if not errorlevel 1 (
+ echo The backend exited right after starting. Last log lines:
+ docker compose logs --tail 20 rest_server
+ echo.
+ echo If it names a missing or retired secret, see "Upgrading: secrets are
+ echo generated per install" in docs/platform/getting-started.md.
+ pause
+ exit /b 1
+)
+docker compose exec -T rest_server python -c "import urllib.request; urllib.request.urlopen('http://localhost:8006/health', timeout=3)" >nul 2>&1
+if not errorlevel 1 goto backend_ready
+set /a BACKEND_TRIES+=1
+if %BACKEND_TRIES% LSS 36 goto backend_wait
+echo The backend has not answered yet. It may still be starting: check
+echo "docker compose logs -f rest_server".
+:backend_ready
+
echo =============================
echo Setup Complete!
echo =============================
@@ -199,6 +228,32 @@ REM ============================================================================
REM Subroutines
REM ============================================================================
+:init_env
+REM The .env.default files leave ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY and
+REM BETTER_AUTH_SECRET blank and the backend refuses to start without an
+REM ENCRYPTION_KEY, so generate them here exactly as `make init-env` does.
+REM Values that are already set are never overwritten. The generator is
+REM stdlib-only Python; it runs in a container because Docker is the one
+REM prerequisite every Windows install already has.
+cd /d "%REPO_DIR%\autogpt_platform"
+if errorlevel 1 (
+ echo Failed to navigate to autogpt_platform directory.
+ exit /b 1
+)
+echo Generating secrets for this install...
+if not exist .env copy /Y .env.default .env >nul
+if not exist backend\.env copy /Y backend\.env.default backend\.env >nul
+if not exist frontend\.env copy /Y frontend\.env.default frontend\.env >nul
+for %%F in (.env backend/.env frontend/.env) do (
+ docker run --rm -v "%REPO_DIR%\autogpt_platform:/platform" -w /platform python:3.13-alpine python3 single-container/runtime_config.py fill-env --path %%F
+ if errorlevel 1 (
+ echo Failed to generate secrets in %%F
+ exit /b 1
+ )
+)
+echo Secrets ready.
+exit /b 0
+
:bootstrap_ollama
if not "%OLLAMA_HOST_URL%"=="" (
REM Normalize remote URL: strip a trailing slash and an optional /v1
@@ -347,7 +402,6 @@ if errorlevel 1 (
echo no backend dir
exit /b 1
)
-if not exist .env copy /Y .env.default .env >nul
set HOST_URL=
if not "%OLLAMA_HOST_URL%"=="" (
diff --git a/autogpt_platform/installer/setup-autogpt.sh b/autogpt_platform/installer/setup-autogpt.sh
index 37cde84bf2..10eb77905f 100755
--- a/autogpt_platform/installer/setup-autogpt.sh
+++ b/autogpt_platform/installer/setup-autogpt.sh
@@ -325,13 +325,40 @@ _bootstrap_ollama_macos() {
print_color "GREEN" "✓ Ollama ready: http://localhost:11434"
}
+init_env() {
+ # The .env.default files leave ENCRYPTION_KEY, UNSUBSCRIBE_SECRET_KEY and
+ # BETTER_AUTH_SECRET blank and the backend refuses to start without an
+ # ENCRYPTION_KEY, so generate them here exactly as `make init-env` does.
+ # Values that are already set are never overwritten.
+ cd "$REPO_DIR/autogpt_platform" || handle_error "Failed to navigate to autogpt_platform"
+ print_color "BLUE" "Generating secrets for this install..."
+
+ local dir
+ for dir in . backend frontend; do
+ [ -f "$dir/.env" ] || cp "$dir/.env.default" "$dir/.env" || handle_error "Failed to create $dir/.env"
+ done
+
+ # The generator is stdlib-only Python. Hosts without python3 run it in a
+ # container instead, as the calling user so the .env files stay readable.
+ local -a generator=(python3)
+ if ! command -v python3 &> /dev/null; then
+ # $DOCKER_CMD may be "sudo docker", so it is split on purpose.
+ generator=($DOCKER_CMD run --rm --user "$(id -u):$(id -g)"
+ -v "$PWD:/platform" -w /platform python:3.13-alpine python3)
+ fi
+ for dir in . backend frontend; do
+ "${generator[@]}" single-container/runtime_config.py fill-env --path "$dir/.env" \
+ || handle_error "Failed to generate secrets in $dir/.env"
+ done
+ print_color "GREEN" "✓ Secrets ready"
+}
+
write_local_env() {
# Wire backend/.env so the new ChatConfig.local transport activates and
# AutoPilot routes through Ollama with no cloud API keys. Uses the host
# LAN IP (or the explicit --ollama-host URL) so containers on Linux
# can reach Ollama without docker-compose extra_hosts gymnastics.
cd "$REPO_DIR/autogpt_platform/backend" || handle_error "no backend dir"
- [ -f .env ] || cp .env.default .env
local host_url
if [ -n "$OLLAMA_HOST_URL" ]; then
# ``bootstrap_ollama`` already stripped the trailing slash + any
@@ -421,6 +448,30 @@ write_local_env() {
print_color "GREEN" "✓ wrote backend/.env (CHAT_USE_LOCAL=true, Ollama at $host_url)"
}
+check_backend_running() {
+ # `up -d` succeeds as soon as the containers are created, so a backend
+ # that exits on startup would otherwise be reported as a working install.
+ # Wait for it to answer rather than for a fixed time: on a slow host the
+ # imports alone can take longer than any short window.
+ print_color "BLUE" "Waiting for the backend to come up..."
+ local attempt
+ for attempt in $(seq 1 36); do
+ sleep 5
+ if $DOCKER_COMPOSE_CMD ps --status exited --services 2>/dev/null | grep -qx rest_server; then
+ print_color "RED" "The backend exited right after starting. Last log lines:"
+ $DOCKER_COMPOSE_CMD logs --tail 20 rest_server
+ print_color "YELLOW" "If it names a missing or retired secret, see 'Upgrading: secrets are generated per install' in docs/platform/getting-started.md."
+ exit 1
+ fi
+ if $DOCKER_COMPOSE_CMD exec -T rest_server python -c \
+ "import urllib.request; urllib.request.urlopen('http://localhost:8006/health', timeout=3)" \
+ &> /dev/null; then
+ return 0
+ fi
+ done
+ print_color "YELLOW" "The backend has not answered yet. It may still be starting: check 'docker compose logs -f rest_server'."
+}
+
run_docker() {
cd "$REPO_DIR/autogpt_platform" || handle_error "Failed to navigate to autogpt_platform"
@@ -432,6 +483,7 @@ run_docker() {
LOG_FILE="$REPO_DIR/autogpt_platform/logs/docker_setup.log"
if $DOCKER_COMPOSE_CMD up -d > "$LOG_FILE" 2>&1; then
+ check_backend_running
print_color "GREEN" "✓ Services started successfully!"
else
print_color "RED" "Docker compose failed. Check log file for details: $LOG_FILE"
@@ -451,6 +503,7 @@ main() {
check_prerequisites
detect_repo
clone_repo
+ init_env
if [ "$WITH_OLLAMA" = true ]; then
bootstrap_ollama
write_local_env
diff --git a/docs/platform/getting-started.md b/docs/platform/getting-started.md
index 04c68246e0..da1c0239d6 100644
--- a/docs/platform/getting-started.md
+++ b/docs/platform/getting-started.md
@@ -157,6 +157,128 @@ Frontend UI Server: 3000
Backend Websocket Server: 8001
Execution API Rest Server: 8006
+### Upgrading: secrets are generated per install
+
+`ENCRYPTION_KEY`, `UNSUBSCRIBE_SECRET_KEY` and `BETTER_AUTH_SECRET` used to
+come with a value in `.env.default`, so every install that did not set its own
+ran on the same three values. They are now blank there and generated for each
+install, and the backend **does not start** without an `ENCRYPTION_KEY` or
+with the one `.env.default` used to contain.
+
+A fresh install needs nothing beyond `make init-env` (or the installer script,
+which does the same). An install that already set its own values needs
+nothing either. Follow the steps below if you are upgrading an install that
+
+- has no `autogpt_platform/backend/.env`, or one without an `ENCRYPTION_KEY`
+ line — it was running on the value from `.env.default`; or
+- stops on startup with `ENCRYPTION_KEY is set to a value that was published…`
+ or `ENCRYPTION_KEY is not set`.
+
+Your connected integrations are encrypted with `ENCRYPTION_KEY`, so the steps
+move them to the new key instead of losing them. Run everything from
+`autogpt_platform/`.
+
+1. Stop the stack:
+
+ ```bash
+ docker compose down
+ ```
+
+2. Keep the key your data is currently encrypted with. If you never set one,
+ it is the value `.env.default` contained up to release `v0.7.4`:
+
+ ```bash
+ export OLD_ENCRYPTION_KEY=$(git show autogpt-platform-beta-v0.7.4:autogpt_platform/backend/.env.default \
+ | grep '^ENCRYPTION_KEY=' | cut -d= -f2-)
+ ```
+
+ If you did set one and are replacing it, export that value instead, and keep
+ a copy of the file outside the checkout until step 4 reports nothing
+ unreadable, because step 3 removes the only other place the key is written
+ down:
+
+ ```bash
+ cp -n backend/.env ~/autogpt-backend.env.before-upgrade
+ ```
+
+3. Generate the new values. `make init-env` creates any missing `.env` file
+ and fills in every secret whose line is present but empty; it never
+ overwrites a value. So in `backend/.env` make sure these two lines exist
+ with nothing after the `=`, and do the same for `BETTER_AUTH_SECRET=` in
+ `frontend/.env`:
+
+ ```
+ ENCRYPTION_KEY=
+ UNSUBSCRIBE_SECRET_KEY=
+ ```
+
+ Then:
+
+ ```bash
+ make init-env
+ ```
+
+ Without `make`, these are the same steps by hand. Copy a `.env.default`
+ only where no `.env` exists yet:
+
+ ```bash
+ cp -n .env.default .env
+ cp -n backend/.env.default backend/.env
+ cp -n frontend/.env.default frontend/.env
+ python3 single-container/runtime_config.py fill-env --path .env
+ python3 single-container/runtime_config.py fill-env --path backend/.env
+ python3 single-container/runtime_config.py fill-env --path frontend/.env
+ ```
+
+ Do not re-run the installer script for this: it also starts the stack,
+ which is step 5.
+
+4. Re-encrypt what is stored. Build the new images and bring the database up
+ to date first; `migrate` starts the database on its own:
+
+ ```bash
+ docker compose build migrate rest_server
+ docker compose run --rm migrate
+ ```
+
+ Then run the command, first as a dry run that only reports what it would
+ change, then with `--apply` to write it. `--no-deps` keeps it from waiting
+ on the rest of the stack, which it does not need:
+
+ ```bash
+ docker compose run --rm --no-deps -e OLD_ENCRYPTION_KEY rest_server cli rotate-encryption-key
+ docker compose run --rm --no-deps -e OLD_ENCRYPTION_KEY rest_server cli rotate-encryption-key --apply
+ ```
+
+ It is safe to run more than once: values already under the new key are left
+ alone, and a value that neither key can read is listed and not touched.
+ Running the backend outside Docker, the same command is
+ `poetry run cli rotate-encryption-key` in `autogpt_platform/backend`.
+
+5. Start the stack again. If `BETTER_AUTH_SECRET` changed in step 3, first
+ clear the token signing key the frontend stored under the old value: it can
+ no longer be decrypted, and until it is removed nobody can reach the
+ backend, even after signing in again. A new one is created on the next
+ sign-in. `--build` brings the remaining services to the release you built
+ in step 4:
+
+ ```bash
+ docker compose up -d --wait db
+ docker compose exec db psql -U postgres -c 'DELETE FROM platform."UserAuthJwks";'
+ docker compose up -d --build
+ ```
+
+Two smaller effects of the new values: unsubscribe links in emails sent before
+the upgrade stop working (`UNSUBSCRIBE_SECRET_KEY`), and everyone signs in
+again once (`BETTER_AUTH_SECRET`).
+
+Do step 4 before step 5. On a new key the stored values are still in the
+database but read as empty, and a user who connects an integration in that
+state replaces their stored set: their other credentials are marked revoked.
+If the stack already ran on the new key, stop it and run step 4 now. Whatever
+nobody touched is recovered; a user who connected something in between gets
+their older credentials re-encrypted but still revoked, and reconnects those.
+
### Upgrading an existing (Supabase-based) installation
Older versions of the platform ran authentication on a bundled Supabase
@@ -173,14 +295,10 @@ three things changed:
The `SUPABASE_*` URL/key variables are gone; the frontend now uses
`BETTER_AUTH_SECRET` and `DATABASE_URL`.
- **Rotate your secrets.** `backend/.env.default` used to ship working values
- for `ENCRYPTION_KEY` and `UNSUBSCRIBE_SECRET_KEY`, and
- `frontend/.env.default` one for `BETTER_AUTH_SECRET`. Those values are
- public. If your `.env` files still carry them, replace each with a freshly
- generated secret — the backend now refuses to start on the published
- `ENCRYPTION_KEY`. Note that rotating `ENCRYPTION_KEY` makes stored
- integration credentials unreadable, so reconnect those integrations
- afterwards.
+ `ENCRYPTION_KEY`, `UNSUBSCRIBE_SECRET_KEY` and `BETTER_AUTH_SECRET` are no
+ longer filled in by `.env.default`: follow
+ [Upgrading: secrets are generated per install](#upgrading-secrets-are-generated-per-install)
+ as part of this step.
2. **Database location**: the database now lives in a plain Postgres
container (`pgvector/pgvector:pg15`) with its data in
`autogpt_platform/data/db/data`. Your old data is untouched at
@@ -313,11 +431,12 @@ Or run the following command in the `autogpt_platform/backend` directory:
poetry run cli gen-encrypt-key
```
-Then replace the value in `autogpt_platform/backend/.env`. **Rotating the key
-makes previously stored integration credentials unreadable**, so you will need
-to reconnect those integrations afterwards. The backend refuses to start on any
-value that was once published in `.env.default`: those must be treated as
-compromised.
+Then replace the value in `autogpt_platform/backend/.env` and re-encrypt the
+stored integration credentials under it, with the previous value as
+`OLD_ENCRYPTION_KEY` — steps 4 and 5 of
+[Upgrading: secrets are generated per install](#upgrading-secrets-are-generated-per-install).
+Without that step the credentials stored under the previous key are unreadable
+and those integrations need reconnecting.
#### Auth transport security (JWKS over untrusted networks)
diff --git a/docs/platform/installer.md b/docs/platform/installer.md
index 23880d4f97..b24e751983 100644
--- a/docs/platform/installer.md
+++ b/docs/platform/installer.md
@@ -199,6 +199,14 @@ If you prefer, you can manually download and run the installer scripts:
These scripts are located in the `autogpt_platform/installer/` directory.
+Both create the three `.env` files if they are missing and generate the
+secrets `.env.default` leaves blank (`ENCRYPTION_KEY`,
+`UNSUBSCRIBE_SECRET_KEY`, `BETTER_AUTH_SECRET`), the same as `make init-env`.
+Running a script again never changes a value that is already set. If you are
+upgrading an install that ran without its own `ENCRYPTION_KEY`, read
+[Upgrading: secrets are generated per install](getting-started.md#upgrading-secrets-are-generated-per-install)
+first so your connected integrations move to the new key.
+
### Running fully offline with a local LLM (Ollama)
Both installer scripts accept an opt-in flag that installs