Skip to main content
Use this runbook if you run Formbricks with your own docker-compose.yml. If you installed with the one-click script, use the one-click runbook instead. This runbook covers upgrades to 6.0 or later. To upgrade to a 4.x or 5.x version, use the 4.x and 5.x procedure. Before you start:
  • Find your next stop in Upgrade paths and read its version page.
  • First upgrade to 6.0? Do the 6.0 setup steps first. They add the new permission services to your Compose file.
  • Plan a maintenance window for a minor or major upgrade. For a patch upgrade, see patch upgrades.
  • Run all commands in your Compose directory, with the same project name and .env file as always.
1

Choose the target version

Replace 6.0.5 with your next stop. Keep this terminal open; later steps use target_version.
2

Update the configuration

Follow the configuration checklist. In short:
  • Set the Formbricks image to ghcr.io/formbricks/formbricks:<target_version> on every service that uses it: formbricks, formbricks-migrate, authzed-ops and authzed-initialize.
  • Set HUB_IMAGE_REF to the Hub version of this release. All Hub services use the same image.
  • Merge any new services or settings named on the version page. Keep your SMTP, storage, proxy and secret settings.
  • Download the Cube model files for the same version.
Then check the file and download the images before the maintenance window:
The first command must print nothing. Pulling images doesn’t add missing services; they must be in your Compose file.
3

Stop the app and back up

Close traffic at your reverse proxy and let running requests finish. Stop every service that writes data:
Also stop any taxonomy worker, scheduled script or external process that writes to Formbricks. Keep the databases running. Then take a backup of the databases, file storage, .env and docker-compose.yml.
4

Prepare permissions (minor and major upgrades)

For an upgrade to a new minor version, start only the databases and prepare the permission data with the new image:
If PostgreSQL or SpiceDB run outside this Compose project, skip the first command and check that they’re healthy instead. Preparation applies the app’s database migrations, then prepares the permissions. It must end with upgrade_prepared. If it fails, keep the app stopped and see permission preparation.When the permission schema changes, as from 6.0 to 6.1, preparation needs the current schema digest: run docker compose --profile authzed-ops run --rm --no-deps authzed-ops schema check, then add --expected-current-digest <remoteDigest> to the command above. See schema changes.For a first upgrade to 6.0, then set FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true in .env.
5

Refresh the Cube model

Skip this if Cube runs outside this Compose project. Otherwise stop Cube and install the model files you downloaded for the target version:
Then follow install the Cube model files.
6

Start the new version

Run the app and Hub migrations, then start everything:
Each command only runs if the one before it succeeds. After permission preparation, the app migrations have nothing left to do. All services must be running, or have exited with code 0 for the migration services.
7

Check that it worked

Do the checks after the upgrade. Then reopen traffic at your proxy. Keep the backup and the old configuration until you’re sure the upgrade is good.

Patch upgrades

A patch, such as 6.1.2 → 6.1.3, doesn’t change the permission schema and normally has no database migrations. Check its upgrade impact in the release notes, then:
  1. Do the steps Choose the target version and Update the configuration above.
  2. Do the step Stop the app and back up above. Starting the new version also runs one-time setup services such as authzed-initialize, which must not write while the old app is still running.
  3. Check that the permission setup is clean. This must exit 0:
  4. Do the step Start the new version above. Skip permission preparation and the Cube refresh unless the patch’s upgrade impact asks for them.

If something goes wrong

Don’t run docker compose down -v: it deletes your data. Going back to the old image doesn’t undo database migrations. Use troubleshooting, or restore the databases, files and configuration together with backup and restore.