> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 6.0: Upgrade guide

> Add SpiceDB, prepare permissions and verify the first v6 deployment.

**Upgrade from:** the latest 5.4 patch. Skipping 5.4 is not supported; see [Upgrade paths](https://formbricks.com/docs/self-hosting/upgrade/paths.md).
**Downtime:** a maintenance window. **Applies to:** all editions and setups.
Already on 6.0? For a later 6.0 patch, see the [patch actions](#patch-actions).

## Before

| Change | Required action |
| - | - |
| SpiceDB becomes required | Add a dedicated datastore/login and private connectivity; prepare its schema and relationships before app startup. |
| Consistency requirement | Set `AUTHZED_CONSISTENCY=fully_consistent`; unset or `minimize_latency` is rejected. |
| SSO provisioning variables | Rename `DEFAULT_ORGANIZATION_ID` / `DEFAULT_ORGANIZATION_ROLE` to `AUTH_SSO_DEFAULT_ORGANIZATION_ID` / `AUTH_SSO_DEFAULT_ORGANIZATION_ROLE`, preserving values. They affect Enterprise just-in-time provisioning. |
| Hidden fields/variables become Embedded Data | Review the [migration behavior](https://formbricks.com/docs/surveys/embedded-data/migration.md), including skipped/conflicting fields; verify old responses and SDK integrations. |
| Response/email and chart changes | The non-functional single-response-per-email option is removed; use signed single-use links when one response per link is required. Line charts become area charts. |

Keep Hub, Cube, Redis, storage, PostgreSQL major and existing credentials. A self-hosted Cloud bridge
is not required. [Prepare the target configuration](https://formbricks.com/docs/self-hosting/upgrade/configuration.md) before maintenance.

### First v6 dependency setup

> [tab] Docker and one-click
>
> These steps add bundled SpiceDB to an existing Compose installation. For external PostgreSQL or
> SpiceDB, use [SpiceDB operations](https://formbricks.com/docs/self-hosting/configuration/authzed-operations.md) 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](https://github.com/formbricks/formbricks/releases).
> Reference files: [Compose](https://github.com/formbricks/formbricks/blob/6.0.4/docker/docker-compose.yml)
> and [database bootstrap](https://github.com/formbricks/formbricks/blob/6.0.4/docker/authzed-postgres-bootstrap.sh).
> The commands below download both from the exact tag you select.
>
> ```bash theme={null}
> read -r -p "Target 6.0 release tag: " target_version
> : "${target_version:?Choose a release first}"
> release_base="https://raw.githubusercontent.com/formbricks/formbricks/${target_version}/docker"
> curl -fsSL "$release_base/docker-compose.yml" -o docker-compose.release.yml &&
>   curl -fsSL "$release_base/authzed-postgres-bootstrap.sh" -o authzed-postgres-bootstrap.sh
> ```
>
> 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:
>
> ```bash theme={null}
> openssl rand -hex 32
> ```
>
> Save the two different results in your existing `.env`:
>
> ```dotenv theme={null}
> AUTHZED_TOKEN=<first-generated-value>
> AUTHZED_DATABASE_PASSWORD=<second-generated-value>
> AUTHZED_ENABLED=true
> AUTHZED_ENDPOINT=spicedb:50051
> AUTHZED_SYSTEM_KEY=formbricks
> AUTHZED_INSECURE=true
> AUTHZED_CONSISTENCY=fully_consistent
> ```
>
> 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](https://formbricks.com/docs/self-hosting/upgrade/prepare.md#docker-and-one-click) 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**
>
> ```bash theme={null}
> docker compose config --quiet
> docker compose --profile authzed-ops config --services
> docker compose --profile authzed-ops config --images
> ```
>
> 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](https://formbricks.com/docs/self-hosting/upgrade/docker.md#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.

> [tab] Kubernetes
>
> **1. Decide where SpiceDB runs**
>
> The 6.0 chart refuses to upgrade a 5.4 release until permission preparation is done, and preparation
> needs a running SpiceDB. So for this first upgrade, SpiceDB must run before you upgrade the Formbricks release:
> either an existing SpiceDB managed by your platform team, or one you deploy separately first. Install
> only one SpiceDB operator per cluster; if your platform team already runs one, set `authzed.operator.install: false`.
>
> **2. Create the SpiceDB database and Secret**
>
> On managed PostgreSQL, such as RDS, create a separate login and database:
>
> ```sql theme={null}
> CREATE ROLE spicedb LOGIN PASSWORD '<password>';
> GRANT spicedb TO CURRENT_USER;   -- needed when you aren't a superuser
> CREATE DATABASE spicedb OWNER spicedb;
> ```
>
> Store the connection and a new token in a Secret:
>
> ```bash theme={null}
> kubectl create secret generic formbricks-authzed -n <namespace> \
>   --from-literal=preshared_key="$(openssl rand -hex 32)" \
>   --from-literal=datastore_uri='postgresql://spicedb:<url-encoded-password>@<host>:5432/spicedb?sslmode=require'
> ```
>
> **3. Add the values**
>
> ```yaml theme={null}
> authzed:
>   enabled: true
>   consistency: fully_consistent
>   auth:
>     existingSecret: formbricks-authzed
>   datastore:
>     existingSecret: formbricks-authzed
>   # For a SpiceDB that runs outside this release:
>   mode: external
>   operator:
>     install: false
>   endpoint: "<host>:<port>"
>   # External endpoints use TLS. Set insecure: true only for a plaintext endpoint inside the cluster.
>   # Set only after permission preparation succeeds:
>   migrationAcknowledged: false
> ```
>
> If your values set `DEFAULT_ORGANIZATION_ID` or `DEFAULT_ORGANIZATION_ROLE`, rename them as shown in the table above.
> See [SpiceDB authorization](https://formbricks.com/docs/self-hosting/setup/kubernetes.md#spicedb-authorization) for all options.
>
> **4. Continue with the runbook**
>
> Follow the [Kubernetes runbook](https://formbricks.com/docs/self-hosting/upgrade/kubernetes.md). Its permission preparation step
> creates the permission data; then you set `authzed.migrationAcknowledged: true` and deploy.

### 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.

| Patch | Upgrade impact |
| - | - |
| 6.0.1 | The storage setup helper switches to the RustFS CLI. Keep your existing MinIO or S3 data and settings. |
| 6.0.2 | Action required if you use the bundled Cube: [6.0.2 Cube image migration](https://formbricks.com/docs/self-hosting/upgrade/versions/cube.md). |
| 6.0.3 | None. Helm AuthZed hooks now run as user `1001`, which only matters for custom hook images. |
| 6.0.4 | Action required for some setups: [6.0.4 security updates](https://formbricks.com/docs/self-hosting/upgrade/versions/2026-10-security-patches.md) (Redis CA, Hub and enrichment, MCP batches). |
| 6.0.5 | Action required for some setups: [6.0.5 security updates](https://formbricks.com/docs/self-hosting/upgrade/versions/2026-10-27-patches.md) (outgoing-email limits). |
| 6.0.6 | None. See [6.0.6](https://formbricks.com/docs/platform/changelog.md#release-6-0-6). |

## Upgrade

Follow the runbook for your setup: [Kubernetes](https://formbricks.com/docs/self-hosting/upgrade/kubernetes.md),
[Docker Compose](https://formbricks.com/docs/self-hosting/upgrade/docker.md) or [one-click](https://formbricks.com/docs/self-hosting/upgrade/one-click.md).
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](https://formbricks.com/docs/self-hosting/upgrade/prepare.md) 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](https://formbricks.com/docs/self-hosting/advanced/upgrade.md#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](https://formbricks.com/docs/self-hosting/operate/backup-restore.md).

All changes: [5.4.0 → 6.0.0](https://github.com/formbricks/formbricks/compare/5.4.0...6.0.0) and
[6.0 patches](https://github.com/formbricks/formbricks/compare/6.0.0...6.0.6).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.