> ## 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 one-click

> Upgrade an installation that was set up with the formbricks.sh one-click script.

Use this runbook if you installed Formbricks with the [one-click script](https://formbricks.com/docs/self-hosting/setup/one-click.md):
you have a `formbricks.sh` file next to a `formbricks/` directory. It 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).

> [!CAUTION]
>
> **Don't run `./formbricks.sh update` until you've pinned the version.** One-click installs use the
> `ghcr.io/formbricks/formbricks:latest` image by default, and the updater pulls whatever the image tag
> points to. On an older installation, that jumps straight to the newest release and skips your upgrade stops.

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. The updater can't add the new 6.0 services for you.
* Plan a maintenance window for a minor or major upgrade. Surveys and the app are unavailable while it runs.
  For a patch upgrade, see [patch upgrades](#patch-upgrades).
* Run the commands below on the server. If your user isn't in the `docker` group, put `sudo` before each `docker` command.

**1. Choose the target version**

Open a terminal in the `formbricks/` directory. Set the version you're upgrading to, for example `6.0.5`:

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

Keep this terminal open. Later steps use `target_version`.

**2. Pin the app and Hub versions**

Replace the Formbricks image tag in `docker-compose.yml` with the target version. This keeps a copy
of the old file as `docker-compose.yml.bak`:

```bash theme={null}
sed -i.bak -E "s#(ghcr\.io/formbricks/formbricks):[^[:space:]\"']+#\1:${target_version}#" docker-compose.yml
grep -n 'ghcr.io/formbricks/' docker-compose.yml
```

Every `ghcr.io/formbricks/formbricks` line must now end in your target version. If a line uses a
digest (`@sha256:…`), replace it by hand.

Then pin Hub to the version that belongs to this release:

```bash theme={null}
hub_tag=$(curl -fsSL "https://raw.githubusercontent.com/formbricks/formbricks/${target_version}/charts/formbricks/values.yaml" |
  grep -A8 'repository: "ghcr.io/formbricks/hub"' | grep 'tag:' | head -1 | sed -E 's/.*"(.*)".*/\1/')
echo "Hub version: ${hub_tag:?Could not find the Hub version}"
cp .env .env.bak
if grep -q '^HUB_IMAGE_REF=' .env; then
  sed -i "s/^HUB_IMAGE_REF=.*/HUB_IMAGE_REF=:${hub_tag}/" .env
else
  echo "HUB_IMAGE_REF=:${hub_tag}" >> .env
fi
```

The colon before the version is intentional.

**3. Download the new images**

Download the images now, before the maintenance window starts:

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

The first command must print nothing. If it shows an error, fix the file before you continue.

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

Stop the services that write data. The databases keep running:

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

Then back up the databases and your configuration:

```bash theme={null}
umask 077
backup_time=$(date -u +%Y%m%dT%H%M%SZ)
docker compose exec -T postgres pg_dump -Fc -U postgres -d formbricks > "../formbricks-${backup_time}.dump" &&
  cp .env.bak "../env-${backup_time}.bak" && cp docker-compose.yml.bak "../docker-compose-${backup_time}.yml"
```

If you already run 6.x, also back up the permission database. Skip this on a first upgrade to 6.0: the
`spicedb` database doesn't exist yet.

```bash theme={null}
docker compose exec -T postgres pg_dump -Fc -U postgres -d spicedb > "../spicedb-${backup_time}.dump"
```

If you use the bundled file storage (RustFS or MinIO), also back up its volume. Find its name with
`docker volume ls`, then:

```bash theme={null}
docker run --rm -v <storage-volume>:/data:ro -v "$PWD/..":/backup alpine \
  tar czf "/backup/storage-${backup_time}.tgz" -C /data .
```

Every command must finish without an error. Copy the backup files to another machine before you continue.

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

For an upgrade to a new minor version, such as 6.0 → 6.1, 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
```

It must end with `upgrade_prepared`. If it stops with an error, 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`.

**6. Run the updater for the target version**

Download the updater that belongs to the target version, then run it from the directory that contains `formbricks/`:

```bash theme={null}
cd ..
curl -fsSL "https://raw.githubusercontent.com/formbricks/formbricks/${target_version}/docker/formbricks.sh" -o formbricks.sh
chmod +x formbricks.sh
./formbricks.sh update
```

The updater checks the permission setup, runs the database migrations and starts all services. It ends
with `Formbricks updated successfully!`. From 6.1, it also refreshes the Cube model files and applies small
fixes for your release, such as the [port binding](https://formbricks.com/docs/self-hosting/upgrade/one-click-details.md).

**Upgrading to a 6.0 patch?** The 6.0 updater doesn't refresh the Cube model files. Before you run it, stop
Cube with `cd formbricks && docker compose stop cube && cd ..`, then
[install the Cube model files](https://formbricks.com/docs/self-hosting/upgrade/configuration.md#download-the-cube-model-files) for the target version.

**7. Check that it worked**

```bash theme={null}
cd formbricks
docker compose ps -a
docker compose logs --tail=100 formbricks
```

All services must be running or have exited with code `0`. Then do the
[checks after the upgrade](https://formbricks.com/docs/self-hosting/advanced/upgrade.md#after-the-upgrade) before you open the app to users again.

## 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 do the steps above, but skip
**Prepare permissions** unless the patch's upgrade impact asks for it. The updater checks the permission setup
itself and stops before changing anything if it isn't clean.

## 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. To return to the old version:

1. Stop the app: `docker compose stop formbricks hub $(docker compose config --services | grep -x hub-worker)`.
2. Restore the databases from your dumps, for example
   `docker compose exec -T postgres pg_restore --clean --if-exists -U postgres -d formbricks < ../formbricks-<time>.dump`,
   and the same for `spicedb` if you backed it up. After a failed first upgrade to 6.0 there is no `spicedb`
   dump to restore: the 5.4 version doesn't use it.
3. Put back the old `docker-compose.yml` and `.env` from your backup, and restore the storage volume if you backed it up.
4. Start the old version with `docker compose up -d`.

See [troubleshooting](https://formbricks.com/docs/self-hosting/upgrade/troubleshooting.md) for common migration errors, and
[backup and restore](https://formbricks.com/docs/self-hosting/operate/backup-restore.md) for the full restore procedure.


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