Skip to main content
Upgrade from: the latest 5.4 patch. Skipping 5.4 is not supported; see Upgrade paths. Downtime: a maintenance window. Applies to: all editions and setups. Already on 6.0? For a later 6.0 patch, see the patch actions.

Before

Keep Hub, Cube, Redis, storage, PostgreSQL major and existing credentials. A self-hosted Cloud bridge is not required. Prepare the target configuration before maintenance.

First v6 dependency setup

These steps add bundled SpiceDB to an existing Compose installation. For external PostgreSQL or SpiceDB, use SpiceDB operations and your platform’s credentials.
1

Download the two release files

Open a terminal in the directory containing your existing docker-compose.yml and .env (usually formbricks/ for one-click). Choose the latest stable 6.0 patch from GitHub releases. Reference files: Compose and database bootstrap. The commands below download both from the exact tag you select.
Continue only if both downloads succeed. docker-compose.release.yml is a reference to compare; keep your existing docker-compose.yml. The script must sit beside it because Compose mounts ./authzed-postgres-bootstrap.sh into the bootstrap container.
2

Create the two new secrets

Run this command twice, once for each missing secret:
Save the two different results in your existing .env:
Replace both placeholders; do not paste openssl commands into .env. Protect it with chmod 600 .env. Keep existing values if these secrets are already configured.
  • AUTHZED_TOKEN is the shared credential used by Formbricks and SpiceDB; no AuthZed account is needed.
  • AUTHZED_DATABASE_PASSWORD is a new password for SpiceDB’s database login. Keep your existing POSTGRES_PASSWORD, auth secrets and encryption key unchanged. If .env has no POSTGRES_PASSWORD yet, add the password your database already uses; older Compose files may store it directly.
  • AUTHZED_SYSTEM_KEY=formbricks is an identifier, not another generated secret. AUTHZED_INSECURE=true is only for the private Compose network; external endpoints should use TLS.
3

Add the services to your existing Compose file

Open docker-compose.release.yml beside docker-compose.yml in your editor:
  1. Copy authzed-db-bootstrap, spicedb-migrate, spicedb, authzed-initialize and authzed-ops under your existing services: key, including their depends_on, mounts and environment blocks. Keep profiles: ["authzed-ops"] on the operations service.
  2. Copy the referenced x-formbricks-database block at the top level and adapt its connection URL to your existing database. Copy the release’s AUTHZED_* bindings and SKIP_STARTUP_MIGRATION setting into the existing formbricks.environment block. Preserve its other settings.
  3. Check POSTGRES_ADMIN_URL on authzed-db-bootstrap uses your existing PostgreSQL admin login. Keep the PostgreSQL image major, volumes and mount paths. Match the bootstrap client’s image to that existing major. Connect all new services to the same private network as PostgreSQL and the app.
  4. Pin formbricks, formbricks-migrate, authzed-initialize and authzed-ops to your selected Formbricks tag. Add WEBAPP_URL with your existing instance URL to authzed-ops.environment for the permission preparation step.
The copied bindings supply the same token to Formbricks and SpiceDB, and the same database password to bootstrap, migration and server containers. .env alone does not add those bindings. Keep your Hub, Cube, storage and proxy configuration. The one-click updater cannot add these services for you.
4

Validate, then continue the maintenance procedure

The first command must exit successfully. Check all five new service names and the selected images in the next two outputs. Resolve missing variables, files or YAML anchors before continuing.Follow Docker upgrade → Prepare migrations and permissions after stopping writers and taking the backup. That step starts the following chain automatically:
  1. authzed-db-bootstrap runs the downloaded script inside Docker. It creates the spicedb database and login if missing, and sets that login’s password to your configured value.
  2. spicedb-migrate creates or updates SpiceDB’s internal tables; spicedb then starts.
  3. You run the separate Formbricks preparation command to migrate application data and populate permissions.
You do not run the bootstrap script on the host. It does not generate secrets or migrate Formbricks permissions. Bootstrap must finish with AuthZed database bootstrap completed., both setup containers must exit 0, and SpiceDB must be healthy. Check with docker compose ps -a and docker compose logs authzed-db-bootstrap spicedb-migrate. Stop on failure; keep the app stopped.

Patch actions

Check each patch you cross. You can go straight to the latest 6.0 patch. Patches within 6.0 don’t change the permission schema, so you don’t run permission preparation for them.

Upgrade

Follow the runbook for your setup: Kubernetes, Docker Compose or one-click. For this first v6 upgrade, the order matters:
  1. Stop the app and workers, and back up.
  2. Start only PostgreSQL and SpiceDB.
  3. Run permission preparation with the 6.0 image. It runs the app’s database migrations, then creates the permission data. It must end with upgrade_prepared.
  4. Only then set the v6 acknowledgement (FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true in .env, or authzed.migrationAcknowledged: true in Helm values) and start the app and Hub.

Check it worked

  • Users can sign in, including existing SSO users, and see only what they should.
  • A scoped API key works for what it’s allowed to do and is refused for everything else. A revoked permission stays revoked.
  • Embedded Data, existing responses, charts, and old and new uploads work.
  • Background jobs run.
Also do the checks after the upgrade, and add the SpiceDB database to your regular backups.

If something goes wrong

Going back to the 5.4 image doesn’t undo the database migrations or the permission data. Keep the maintenance window open, and either fix the problem and run preparation again, or restore the 5.4 database backup together with your 5.4 configuration. Never delete volumes. See backup and restore. All changes: 5.4.0 → 6.0.0 and 6.0 patches.