Skip to main content
Use this checklist at each upgrade stop. Work on a copy of your configuration before maintenance; do not start the target services yet.

Download the selected release

Run these commands in the directory containing your existing docker-compose.yml and .env (usually formbricks/ for one-click). Choose the exact tag from GitHub releases for your next stop, not an RC or a moving stable tag. target_version is a shell variable for downloads; it does not change deployed images.
Stop if the download fails. Keep this reference separate from the running configuration.

Merge the release configuration

Open docker-compose.release.yml and your existing docker-compose.yml side by side:
1

Copy complete services

Copy each new service named in the version notes under the existing services: key. Include its environment, mounts, healthcheck and dependencies; copying only image: misses required changes.
2

Copy referenced YAML blocks

Copy any referenced top-level x-... YAML blocks. For example, *formbricks-database needs the matching &formbricks-database definition. Adapt connection URLs to your existing credentials.
3

Preserve existing settings

Add the new app settings to its existing environment block. Keep local networks, proxy labels, SMTP, SSO, storage, volumes and secrets. A customized network must also reach the new services.
Do not replace your whole Compose file. The downloaded reference can contain latest even at an old Git tag. Before pulling: For example, 5.4.7 and 6.0.4 select Hub 0.14.1: use HUB_IMAGE_REF=:0.14.1, including the colon. Select future versions from their own release assets instead of reusing this example indefinitely.

Download the Cube model files

For a bundled Cube service, download both files from the same target tag. These commands only stage files; they do not change the running service. They also work for a first v5 installation of Cube.
Continue only if both downloads succeed. Compare any local customizations. During maintenance, with Cube stopped, back up the existing cube/ directory if present, then install both files:
Do not start Cube unless both copies succeed. The release’s service mounts these two paths. Keep the old pair with your recovery backup; for v4 targets, skip this section because Cube is not used.

Preserve existing state

  • Keep the Compose project name, named volumes/PVCs, database names, credentials, encryption keys and auth secrets.
  • Preserve SMTP, enterprise license, proxy labels, TLS, custom networks, SSO and all storage settings.
  • Some v5 Compose files embed postgres:postgres in database URLs. Wire your existing credentials into app, migration, Hub and Cube connections; adding POSTGRES_PASSWORD alone does not rewrite those URLs.
  • Do not rotate ENCRYPTION_KEY during an upgrade. It is needed to read existing encrypted data.
  • For Helm, merge your overrides into the target chart’s defaults, render privately, and check all images, Secrets, PVC bindings and hooks. Avoid blindly applying --reuse-values across changed chart schemas.

Prepare Helm values

For Helm, start from your existing values.yaml (or values tracked in GitOps). Download the target chart’s defaults as a separate reference:
Replace <target-chart-version> with the chart version selected in your plan; it is not necessarily the app version. Copy only the new settings required by your version notes into your existing overrides. Keep Secrets, PVCs, database credentials and existing operators. Render using your normal release name, namespace and values before following the Kubernetes rollout. Store rendered manifests privately because they can contain secrets. A successful render is not a database-connectivity test.

Existing MinIO and Traefik

You can keep MinIO through the S3 interface. A Formbricks upgrade does not require moving existing files to RustFS. Preserve:
  • The MinIO volume, bucket and credentials; S3_ACCESS_KEY, S3_SECRET_KEY, S3_REGION, S3_BUCKET_NAME, S3_ENDPOINT_URL and S3_FORCE_PATH_STYLE.
  • Traefik labels, networks, TLS and the public files hostname routing to the S3 API, not its console.
  • Bucket CORS for the application/survey origins. Confirm both old files and a new upload work in a browser.
Plan a storage migration separately if your storage service needs replacement. Keep edge rate limiting in place too: Traefik routing alone does not supply the v5 rate-limit requirements.

Add only new secrets

For each missing secret, run this command once in your terminal:
Use a different result for each secret. Save the generated text in your existing .env (for example, HUB_API_KEY=<generated-value>) or secret manager; do not put the generation command itself in the file. For Compose, run chmod 600 .env. Keep existing values on later upgrades. An entry in .env is only available to a service if Compose interpolates it or loads it through env_file. Verify the actual bindings privately; do not paste expanded configuration or secrets into tickets.

Check before maintenance

Resolve every missing variable and unexpected image. Confirm the target image, migration executable and required dependency images can be pulled. Configuration validation does not test database access or migrations; complete the rehearsal before production.