Download the selected release
Run these commands in the directory containing your existingdocker-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.
Merge the release configuration
Opendocker-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.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.cube/ directory if present, then install both files:
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:postgresin database URLs. Wire your existing credentials into app, migration, Hub and Cube connections; addingPOSTGRES_PASSWORDalone does not rewrite those URLs. - Do not rotate
ENCRYPTION_KEYduring 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-valuesacross changed chart schemas.
Prepare Helm values
For Helm, start from your existingvalues.yaml (or values tracked in GitOps). Download the target
chart’s defaults as a separate reference:
<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_URLandS3_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.
Add only new secrets
For each missing secret, run this command once in your terminal:.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.