> ## 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 Docker Compose

> Upgrade a Docker Compose installation that you manage yourself.

Use this runbook if you run Formbricks with your own `docker-compose.yml`. If you installed with the
one-click script, use the [one-click runbook](https://formbricks.com/docs/self-hosting/upgrade/one-click.md) instead. This runbook covers
upgrades **to 6.0 or later**. To upgrade to a 4.x or 5.x version, use the [4.x and 5.x procedure](https://formbricks.com/docs/self-hosting/upgrade/legacy.md).

Before you start:

* Find your next stop in [Upgrade paths](https://formbricks.com/docs/self-hosting/upgrade/paths.md) and read its version page.
* **First upgrade to 6.0?** Do the [6.0 setup steps](https://formbricks.com/docs/self-hosting/upgrade/versions/6.0.md#first-v6-dependency-setup)
  first. They add the new permission services to your Compose file.
* Plan a maintenance window for a minor or major upgrade. For a patch upgrade, see [patch upgrades](#patch-upgrades).
* Run all commands in your Compose directory, with the same project name and `.env` file as always.

**1. Choose the target version**

```bash theme={null}
target_version=6.0.5
```

Replace `6.0.5` with your next stop. Keep this terminal open; later steps use `target_version`.

**2. Update the configuration**

Follow the [configuration checklist](https://formbricks.com/docs/self-hosting/upgrade/configuration.md). In short:

* Set the Formbricks image to `ghcr.io/formbricks/formbricks:<target_version>` on every service that uses it:
  `formbricks`, `formbricks-migrate`, `authzed-ops` and `authzed-initialize`.
* Set `HUB_IMAGE_REF` to the Hub version of this release. All Hub services use the same image.
* Merge any new services or settings named on the version page. Keep your SMTP, storage, proxy and secret settings.
* Download the [Cube model files](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#download-the-cube-model-files) for the same version.

Then check the file and download the images before the maintenance window:

```bash theme={null}
docker compose config --quiet && docker compose pull
```

The first command must print nothing. Pulling images doesn't add missing services; they must be in your Compose file.

**3. Stop the app and back up**

Close traffic at your reverse proxy and let running requests finish. Stop every service that writes data:

```bash theme={null}
docker compose stop formbricks hub $(docker compose config --services | grep -x hub-worker)
```

Also stop any taxonomy worker, scheduled script or external process that writes to Formbricks.
Keep the databases running. Then take a [backup](https://formbricks.com/docs/self-hosting/operate/backup-restore.md) of the databases,
file storage, `.env` and `docker-compose.yml`.

**4. Prepare permissions (minor and major upgrades)**

For an upgrade to a new minor version, start only the databases and prepare the permission data with the new image:

```bash theme={null}
docker compose up -d --wait postgres spicedb
docker compose --profile authzed-ops run --rm --no-deps \
  --entrypoint formbricks-authzed-prepare authzed-ops \
  --backup-confirmed --writers-stopped
```

If PostgreSQL or SpiceDB run outside this Compose project, skip the first command and check that they're healthy instead.
Preparation applies the app's database migrations, then prepares the permissions. It must end with
`upgrade_prepared`. If it fails, keep the app stopped and see [permission preparation](https://formbricks.com/docs/self-hosting/upgrade/prepare.md#results-and-recovery).

When the permission schema changes, as from 6.0 to 6.1, preparation needs the current schema digest:
run `docker compose --profile authzed-ops run --rm --no-deps authzed-ops schema check`, then add
`--expected-current-digest <remoteDigest>` to the command above. See [schema changes](https://formbricks.com/docs/self-hosting/upgrade/prepare.md#schema-changes).

For a first upgrade to 6.0, then set `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true` in `.env`.

**5. Refresh the Cube model**

Skip this if Cube runs outside this Compose project. Otherwise stop Cube and install the model files
you downloaded for the target version:

```bash theme={null}
docker compose stop cube
```

Then follow [install the Cube model files](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#download-the-cube-model-files).

**6. Start the new version**

Run the app and Hub migrations, then start everything:

```bash theme={null}
docker compose run --rm --no-deps formbricks-migrate &&
  docker compose run --rm --no-deps hub-migrate &&
  docker compose up -d
docker compose ps -a
```

Each command only runs if the one before it succeeds. After permission preparation, the app migrations have
nothing left to do. All services must be running, or have
exited with code `0` for the migration services.

**7. Check that it worked**

Do the [checks after the upgrade](https://formbricks.com/docs/self-hosting/advanced/upgrade.md#after-the-upgrade). Then reopen traffic
at your proxy. Keep the backup and the old configuration until you're sure the upgrade is good.

## Patch upgrades

A patch, such as 6.1.2 → 6.1.3, doesn't change the permission schema and normally has no database migrations.
Check its upgrade impact in the [release notes](https://formbricks.com/docs/platform/changelog.md), then:

1. Do the steps **Choose the target version** and **Update the configuration** above.

2. Do the step **Stop the app and back up** above. Starting the new version also runs one-time setup services
   such as `authzed-initialize`, which must not write while the old app is still running.

3. Check that the permission setup is clean. This must exit `0`:

   ```bash theme={null}
   docker compose --profile authzed-ops run --rm --no-deps authzed-ops upgrade check
   ```

4. Do the step **Start the new version** above. Skip permission preparation and the Cube refresh unless the
   patch's upgrade impact asks for them.

## If something goes wrong

Don't run `docker compose down -v`: it deletes your data. Going back to the old image doesn't undo
database migrations. Use [troubleshooting](https://formbricks.com/docs/self-hosting/upgrade/troubleshooting.md), or restore the
databases, files and configuration together with [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.