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
- Docker and one-click
- Kubernetes
- Download the target Compose reference into your existing Compose directory. Use the exact tag of your target version.
- Copy
hub,hub-migrateandcubeunder your existingservices:key. For targets 5.1 or later, also copyformbricks-migrate. Include their dependencies, environment and mounts, following the merge checklist. - Generate missing secrets for
HUB_API_KEYandCUBEJS_API_SECRET. Add the target’sHUB_*andCUBEJS_*app environment bindings; bundled endpoints arehttp://hub:8080andhttp://cube:4000respectively. For targets 5.1 or later, also copySKIP_STARTUP_MIGRATION: "true"intoformbricks.environment; migrations run separately. - Download both Cube model files.
Install them during maintenance. Run
docker compose config --quietand 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.jsandschema/FeedbackRecords.js. Use its Node healthcheck; old examples usingwgetfail 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_SSOenables automatic team provisioning, supply a validAUTH_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.
Single-use links and custom clients
- Unencrypted single-use links now require a survey-bound
suTokenas well assuId. 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 arbitrarysuIdto 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/updatedAton 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-levelAI_* 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 provideformbricks-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.