Before
- Prepare release-matched configuration. Preserve databases, volumes, storage, proxy settings and secrets. Pull the selected images without starting them.
- For a first v5 upgrade, add Hub, Cube, their secrets and edge rate limiting before starting the app.
- Plan downtime for surveys, APIs and admin access. Prepare a recovery point for every affected datastore.
During
- Docker and one-click
- Kubernetes and GitOps
Run from your existing Compose directory, with its normal project name and environment file.
Use these explicit steps for historical upgrades; today’s one-click updater can require v6 services.
-
Close traffic at the proxy and stop
formbricks. Stop Hub, workers and scheduled/external writers if present. Leave databases running and take the coordinated backup. -
Install the updated configuration and Cube model files
(v5 targets only). Stop Cube before replacing its files if it is already running. For the bundled
database/cache, run
docker compose up -d --wait postgres redis; keep the same PostgreSQL major and volumes. Verify external infrastructure through its own deployment instead. -
For a 5.1–5.4 target, run application migrations, then Hub migrations explicitly:
Both commands must finish with exit
0. The target Compose file’s app migration command may have a 300-second timeout. Measure large migrations in rehearsal and review that limit before maintenance. See the 5.4 index procedure for large response tables. - For a 4.x target, migrations run on app startup. The original 5.0 target also runs app migrations at startup, with Hub migrations in its separate service. Keep traffic closed until all migrations complete. Upgrade one minor version at a time; see Upgrade paths.
-
Start the stack with
docker compose up -d. Inspectdocker compose ps -aand migration logs; a running app alone does not prove Hub migrations completed.
authzed-ops service or v6 acknowledgement applies to these targets.After
Complete the acceptance checklist and every release-specific backfill. Check existing-user SSO and old uploads, not only a newly created survey. Only reopen traffic or advance to the next stop after acceptance.Recovery
Keep maintenance active on failure. Restore matching images, configuration and coordinated data if repair cannot complete. Schema renames, dropped columns and data rewrites can make an image-only downgrade unsafe. Never rundocker compose down -v. See backup and restore.