Skip to main content
Applies to: 4.x installations entering 5.x, both editions, Docker/one-click and Kubernetes. The recommended path uses the latest 5.4 patch as the v5 stop. Also apply 5.1, 5.2, 5.3 and 5.4 changes when targeting that stop.

Before

Use Prepare the target configuration for release-matched files, secret generation and service bindings. The one-click updater does not merge the v5 stack into a customized Compose file; pulling images alone cannot add the services.

Hub, Cube and databases

  1. Download the target Compose reference into your existing Compose directory. Use the exact tag of your target version.
  2. Copy hub, hub-migrate and cube under your existing services: key. For targets 5.1 or later, also copy formbricks-migrate. Include their dependencies, environment and mounts, following the merge checklist.
  3. Generate missing secrets for HUB_API_KEY and CUBEJS_API_SECRET. Add the target’s HUB_* and CUBEJS_* app environment bindings; bundled endpoints are http://hub:8080 and http://cube:4000 respectively. For targets 5.1 or later, also copy SKIP_STARTUP_MIGRATION: "true" into formbricks.environment; migrations run separately.
  4. Download both Cube model files. Install them during maintenance. Run docker compose config --quiet and check the image pins before pulling.
  • Hub can share application PostgreSQL or use HUB_DATABASE_URL. Include either choice in backup/restore. Verify pgvector support and the migration role’s permissions on the chosen database.
  • Keep Hub API, migration and worker images matched. Historical Docker assets use a floating Hub tag; pin the version selected by your target release before pulling.
  • Copy the target’s whole Cube service and its cube.js and schema/FeedbackRecords.js. Use its Node healthcheck; old examples using wget fail on images without that executable.
  • Keep existing database credentials. Some v5 examples embed the default password in connection URLs; update the app, migration, Hub and Cube bindings explicitly.

Existing integrations and SSO

  • Data-bearing development environments become separate workspaces; production data remains in its workspace. The old environment table is removed after backfill. Check workspace memberships, API-key scope and webhooks.
  • Legacy Environment IDs have a compatibility mapping. Follow the Workspace ID migration guide when updating SDK configuration; verify existing embedded surveys before changing IDs.
  • If AUTH_SKIP_INVITE_FOR_SSO enables automatic team provisioning, supply a valid AUTH_SSO_DEFAULT_TEAM_ID. Test both existing-user sign-in and new-user provisioning.
  • When crossing 5.2, register its new SSO callback before restart.
  • Unencrypted single-use links now require a survey-bound suToken as well as suId. Old unsigned links, including hand-built custom IDs, are rejected after upgrading from v4.
  • Plan to regenerate and redistribute affected links after deploying v5. Use the share modal or GET /api/v1/management/surveys/{surveyId}/singleUseIds; retain the full returned URL. Do not append an arbitrary suId to a survey URL and expect it to work.
  • Encrypted links have a separate signature change in 6.1. If upgrading through both majors in one window, regenerate links on the final target.
  • Custom v1/v2 client-response integrations can no longer choose createdAt / updatedAt on creation; the server sets them. Verify any imports using those public client endpoints against the target API contract.

Optional AI

AI is not required to complete the v5 upgrade. Configure instance-level AI_* settings only for enabled features. Bundled taxonomy/Qwen services belong to later v5 assets; use your target release’s configuration, not a newer example. Invalid provider credentials can prevent an enabled service from starting.

During

Follow the 4.x/5.x maintenance procedure. Stop writers, take coordinated backups, apply app migrations before Hub migrations, then start the stack. The original 5.0 assets run app migrations at startup; 5.1 and later provide formbricks-migrate separately. Use the target’s ordering rather than copying a current startup command.

After

  • Sign in as an existing user and verify production/development workspaces and permissions.
  • Regenerate affected single-use links, submit a response, check SDK/API integrations and verify Hub-backed feedback/jobs.
  • Open analytics, old files and a new upload; test public routes through the proxy and edge rate limiter.
  • Complete the shared acceptance checks before advancing to v6.

Recovery

The environment/workspace migration renames tables and removes old columns. Reverting to a v4 image alone is unsafe. Restore the pre-v5 database, files, configuration and images together using backup and restore. All changes: 4.9.7 → 5.0.0, target 5.4.7 Compose.