Skip to main content
Use this runbook if you installed Formbricks with the one-click script: you have a formbricks.sh file next to a formbricks/ directory. It 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.
Don’t run ./formbricks.sh update until you’ve pinned the version. One-click installs use the ghcr.io/formbricks/formbricks:latest image by default, and the updater pulls whatever the image tag points to. On an older installation, that jumps straight to the newest release and skips your upgrade stops.
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. The updater can’t add the new 6.0 services for you.
  • Plan a maintenance window for a minor or major upgrade. Surveys and the app are unavailable while it runs. For a patch upgrade, see patch upgrades.
  • Run the commands below on the server. If your user isn’t in the docker group, put sudo before each docker command.
1

Choose the target version

Open a terminal in the formbricks/ directory. Set the version you’re upgrading to, for example 6.0.5:
Keep this terminal open. Later steps use target_version.
2

Pin the app and Hub versions

Replace the Formbricks image tag in docker-compose.yml with the target version. This keeps a copy of the old file as docker-compose.yml.bak:
Every ghcr.io/formbricks/formbricks line must now end in your target version. If a line uses a digest (@sha256:…), replace it by hand.Then pin Hub to the version that belongs to this release:
The colon before the version is intentional.
3

Download the new images

Download the images now, before the maintenance window starts:
The first command must print nothing. If it shows an error, fix the file before you continue.
4

Stop the app and back up

Stop the services that write data. The databases keep running:
Then back up the databases and your configuration:
If you already run 6.x, also back up the permission database. Skip this on a first upgrade to 6.0: the spicedb database doesn’t exist yet.
If you use the bundled file storage (RustFS or MinIO), also back up its volume. Find its name with docker volume ls, then:
Every command must finish without an error. Copy the backup files to another machine before you continue.
5

Prepare permissions (minor and major upgrades)

For an upgrade to a new minor version, such as 6.0 → 6.1, prepare the permission data with the new image:
It must end with upgrade_prepared. If it stops with an error, 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.
6

Run the updater for the target version

Download the updater that belongs to the target version, then run it from the directory that contains formbricks/:
The updater checks the permission setup, runs the database migrations and starts all services. It ends with Formbricks updated successfully!. From 6.1, it also refreshes the Cube model files and applies small fixes for your release, such as the port binding.Upgrading to a 6.0 patch? The 6.0 updater doesn’t refresh the Cube model files. Before you run it, stop Cube with cd formbricks && docker compose stop cube && cd .., then install the Cube model files for the target version.
7

Check that it worked

All services must be running or have exited with code 0. Then do the checks after the upgrade before you open the app to users again.

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 do the steps above, but skip Prepare permissions unless the patch’s upgrade impact asks for it. The updater checks the permission setup itself and stops before changing anything if it isn’t clean.

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. To return to the old version:
  1. Stop the app: docker compose stop formbricks hub $(docker compose config --services | grep -x hub-worker).
  2. Restore the databases from your dumps, for example docker compose exec -T postgres pg_restore --clean --if-exists -U postgres -d formbricks < ../formbricks-<time>.dump, and the same for spicedb if you backed it up. After a failed first upgrade to 6.0 there is no spicedb dump to restore: the 5.4 version doesn’t use it.
  3. Put back the old docker-compose.yml and .env from your backup, and restore the storage volume if you backed it up.
  4. Start the old version with docker compose up -d.
See troubleshooting for common migration errors, and backup and restore for the full restore procedure.