Skip to main content
Use this procedure when the target is 4.x or 5.x. For a v6 target, use the Docker or Kubernetes procedure instead. Choose release stops, read all crossed version notes and rehearse first.

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

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.
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Start the stack with docker compose up -d. Inspect docker compose ps -a and migration logs; a running app alone does not prove Hub migrations completed.
No SpiceDB command, 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 run docker compose down -v. See backup and restore.