> ## 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.

# Upgrade within 4.x or to 5.x

> Maintenance procedure for historical releases before SpiceDB was introduced.

Use this procedure when the **target is 4.x or 5.x**. For a v6 target, use the
[Docker](https://formbricks.com/docs/self-hosting/upgrade/docker.md) or [Kubernetes](https://formbricks.com/docs/self-hosting/upgrade/kubernetes.md) procedure instead.
Choose [release stops](https://formbricks.com/docs/self-hosting/upgrade/paths.md), read all crossed version notes and
[rehearse](https://formbricks.com/docs/self-hosting/upgrade/rehearse.md) first.

## Before

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

> [tab] Docker and one-click
>
> 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](https://formbricks.com/docs/self-hosting/operate/backup-restore.md).
> 2. Install the updated configuration and [Cube model files](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#download-the-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:
>
>    ```bash theme={null}
>    docker compose run --rm --no-deps formbricks-migrate &&
>      docker compose run --rm --no-deps hub-migrate
>    ```
>
>    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](https://formbricks.com/docs/self-hosting/upgrade/versions/5.4-database.md) 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](https://formbricks.com/docs/self-hosting/upgrade/paths.md).
> 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.

> [tab] Kubernetes and GitOps
>
> 1. Render the selected published chart with `--version <selected-chart-version>`, your
>    `-f <values-file>` and explicit images. Keep Secret names,
>    PVCs, external datastores and operator ownership. Check which migration hooks this chart actually ships.
> 2. Close ingress traffic; pause GitOps, autoscalers, schedules and all app/Hub writers. Take coordinated backups.
> 3. Apply prerequisite infrastructure and Secrets. Deploy the selected chart with `--wait --wait-for-jobs`
>    and a rehearsed timeout. Monitor application migrations and, for v5, Hub migrations in order.
>    Argo CD hooks and Helm hooks differ; inspect the rendered hooks for your deployment method.
> 4. Keep ingress closed through the checks below, then resume controllers against the new desired state.
>
> Do not add v6 permission Jobs or `authzed.migrationAcknowledged` to a v4/v5 release.

## After

Complete the [acceptance checklist](https://formbricks.com/docs/self-hosting/upgrade/rehearse.md#acceptance-at-every-stop) 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](https://formbricks.com/docs/self-hosting/operate/backup-restore.md).


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