> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 5.0: Upgrade guide

> Add Hub and Cube, preserve existing infrastructure, and migrate environments to workspaces.

**Applies to:** 4.x installations entering 5.x, both editions, Docker/one-click and Kubernetes.
The [recommended path](https://formbricks.com/docs/self-hosting/upgrade/paths.md) uses the latest 5.4 patch as the v5 stop. Also apply
[5.1](https://formbricks.com/docs/self-hosting/upgrade/versions/5.1.md), [5.2](https://formbricks.com/docs/self-hosting/upgrade/versions/5.2.md),
[5.3](https://formbricks.com/docs/self-hosting/upgrade/versions/5.3.md) and [5.4](https://formbricks.com/docs/self-hosting/upgrade/versions/5.4.md) changes when targeting that stop.

## Before

| Change | Required action |
| - | - |
| Hub becomes mandatory | Add Hub and its migration service; configure `HUB_API_URL` and `HUB_API_KEY`. Include its worker where supplied by your deployment. |
| Cube becomes mandatory | Add Cube, both model files, `CUBEJS_API_URL` and `CUBEJS_API_SECRET`. Allow additional memory; the original sizing estimate is about 500 MB. |
| Edge rate limiting | Protect the documented public/API-key routes with Envoy or equivalent coverage before exposing v5. Keep Redis for remaining app limits. |
| Unencrypted single-use links gain signatures | Regenerate affected links after the v5 upgrade; preserve the full signed URL in custom integrations. |
| Projects/environments become workspaces | Back up before the schema/data migration. Check development-environment data and integration scope after it. |
| New fresh-install defaults | Preserve your PostgreSQL major, MinIO/S3 storage, proxy and credentials. Do not replace them with the new defaults. |

Use [Prepare the target configuration](https://formbricks.com/docs/self-hosting/upgrade/configuration.md) 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

> [tab] Docker and one-click
>
> 1. [Download the target Compose reference](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#download-the-selected-release)
>    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](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#merge-the-release-configuration).
> 3. [Generate missing secrets](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#add-only-new-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](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#download-the-cube-model-files).
>    Install them during maintenance. Run `docker compose config --quiet` and check the
>    [image pins](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#merge-the-release-configuration) before pulling.

> [tab] Kubernetes
>
> Merge the target chart's values into your overrides. Keep `hub.enabled=true` and configure its
> API key from your Secret. For external Cube, set `cube.enabled=false` and configure its endpoint
> and matching secret; otherwise retain the bundled Cube service. Render the chart before deploying.

* 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](https://formbricks.com/docs/surveys/website-app-surveys/workspace-id-migration.md)
  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](https://formbricks.com/docs/self-hosting/upgrade/versions/5.2.md) before restart.

### Single-use links and custom clients

* 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](https://formbricks.com/docs/self-hosting/upgrade/versions/6.1-single-use-links.md).
  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](https://formbricks.com/docs/self-hosting/upgrade/legacy.md).
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](https://formbricks.com/docs/self-hosting/upgrade/rehearse.md#acceptance-at-every-stop) 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](https://formbricks.com/docs/self-hosting/operate/backup-restore.md).

All changes: [4.9.7 → 5.0.0](https://github.com/formbricks/formbricks/compare/4.9.7...5.0.0),
[target 5.4.7 Compose](https://github.com/formbricks/formbricks/blob/5.4.7/docker/docker-compose.yml).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.