Migration - Documentation

v5.2

Formbricks v5.2 migrates authentication from NextAuth to Better Auth. For most self-hosted instances this is a drop-in upgrade, but if you use SSO (Azure AD / Entra ID, generic OIDC, or SAML) you must re-register the OAuth callback URL at your identity provider before the first v5.2 restart, or SSO sign-in will fail with a redirect-URI mismatch.

All users are signed out once when you upgrade to v5.2. Better Auth takes over session handling and there is no dual-read from the old NextAuth sessions, so the cutover is a one-time forced re-login. Passwords are preserved — existing credential hashes are migrated automatically, so no password reset is needed.

SSO Callback URL Change (action required for SSO users)

Better Auth serves the OAuth2/OIDC callback at a new path:

old (NextAuth): /api/auth/callback/{provider}
new (Better Auth): /api/auth/oauth2/callback/{providerId}

Update the redirect / callback URIs at your identity provider to the new path. Replace https://your-domain.com with your instance URL:

Provider	Where to update	New callback URL
Azure AD / Entra ID	Azure portal -> App registration -> Authentication -> Redirect URIs	`https://your-domain.com/api/auth/oauth2/callback/azuread`
Generic OIDC	At your OIDC provider	`https://your-domain.com/api/auth/oauth2/callback/openid`
SAML (BoxyHQ / Jackson)	The Jackson connection’s `redirect_uri`	`https://your-domain.com/api/auth/oauth2/callback/saml`

Google and GitHub sign-in do not change. They use Better Auth’s built-in social providers, whose callback path (/api/auth/callback/{provider}) is unchanged — nothing to do there.For SAML, only the Jackson connection’s redirect_uri changes. The IdP-side ACS endpoint (/api/auth/saml/callback) is unchanged, so you do not need to reconfigure your IdP’s SAML app.Leave the old /api/auth/callback/* redirect URIs registered through the transition. Keeping them in place is harmless and makes a rollback to v5.1 clean.

Authentication Environment Variables

Better Auth introduces two optional variables. Neither is required for a standard upgrade — both fall back to your existing NextAuth configuration:

BETTER_AUTH_SECRET — cookie/session signing secret. Falls back to NEXTAUTH_SECRET when unset. If you set it explicitly it must be at least 32 characters. Keeping the NEXTAUTH_SECRET fallback is recommended so the value the forward-auth proxy already verifies with stays consistent.
BETTER_AUTH_URL — the auth base URL. Falls back to NEXTAUTH_URL (and then WEBAPP_URL) when unset.

If your instance already sets NEXTAUTH_SECRET and NEXTAUTH_URL (all v5.1 instances do), you can upgrade without adding any new auth variables.

Removed: DISABLE_ACCOUNT_DELETION_SSO_CONFIRMATION no longer exists. Remove it from your environment if you set it; it now has no effect.

Optional New Configuration

None of the following is required to run v5.2. Add them only if you want the associated feature.

Hub Enrichment (sentiment, emotion, translation)

Hub >= 0.8.0 can classify sentiment and emotion and translate feedback. These are off unless you set a provider and model, and they run in both the Hub API and the hub-worker, so set the variables on both services. Bump your Hub image to >= 0.8.0 (via HUB_IMAGE_REF) to pick up these features.

SENTIMENT_PROVIDER, SENTIMENT_MODEL, SENTIMENT_PROVIDER_API_KEY
EMOTIONS_PROVIDER, EMOTIONS_MODEL, EMOTIONS_PROVIDER_API_KEY
TRANSLATION_PROVIDER, TRANSLATION_MODEL, TRANSLATION_PROVIDER_API_KEY, TRANSLATION_DEFAULT_LANGUAGE

Supported providers: openai, google (AI Studio, needs *_PROVIDER_API_KEY), and google-gemini (Vertex, needs *_GOOGLE_CLOUD_PROJECT / *_LOCATION plus Application Default Credentials).

A provider set without its required credentials crash-loops both Hub containers on startup — it does not degrade gracefully. Set the credentials, or leave the provider unset.

AI Taxonomy (beta)

An optional standalone taxonomy service, enabled in Docker Compose with COMPOSE_PROFILES=taxonomy. It shares an internal token with Hub:

TAXONOMY_SERVICE_URL (the internal URL to the taxonomy service)
HUB_INTERNAL_API_TOKEN, TAXONOMY_SERVICE_TOKEN (strong random secrets)
TAXONOMY_LLM_PROVIDER / TAXONOMY_LLM_MODEL / TAXONOMY_LLM_BASE_URL / TAXONOMY_LLM_API_KEY (openai-compatible by default; bedrock and vertex-gemini also supported)
TAXONOMY_IMAGE_REF to pin a released image (e.g. :v0.1.0)

Use COMPOSE_PROFILES=qwen,taxonomy to back it with the bundled Qwen/vLLM service.

Bundled Qwen / vLLM Runtime

Docker Compose can now run a bundled OpenAI-compatible LLM for self-hosted AI features with COMPOSE_PROFILES=qwen. Tunable via QWEN_VLLM_IMAGE, QWEN_MODEL_ID, QWEN_SERVED_MODEL_NAME, QWEN_MAX_MODEL_LEN, QWEN_MAX_NUM_SEQS, QWEN_GPU_MEMORY_UTILIZATION, QWEN_VLLM_HOST, and QWEN_VLLM_PORT.

OpenTelemetry Log Export

OTEL_LOGS_ENABLED=1 — export Pino application logs via OTLP (off by default; also needs OTEL_EXPORTER_OTLP_ENDPOINT).

Upgrade Steps

v5.2 requires no manual database migration step beyond the standard automatic Prisma migrations on startup (the credential-account backfill runs automatically). The Helm chart is unchanged from v5.1.

If you use SSO, add the new /api/auth/oauth2/callback/{providerId} redirect URIs at your IdP (see the table above), keeping the old ones in place.
Back up your database.
Pull the v5.2 images and restart (docker compose pull && docker compose down && docker compose up -d, or helm upgrade with the new tag).
After startup, sign in again (the one-time forced re-login) and verify each configured SSO provider completes sign-in.

Rollback

Because the old /api/auth/callback/* redirect URIs are left in place, rolling back to v5.1 is clean: revert your image tags / Helm values, and the previous NextAuth callback path works again. Restore the database backup only if you need to undo schema changes.

v5

Formbricks v5 changes the self-hosted runtime contract. If you are upgrading an existing Formbricks 4.x deployment, review this section before starting the new version.

What Changes In v5

Formbricks Hub is now mandatory for self-hosted Formbricks v5 deployments.
Cube is now part of the baseline stack alongside Hub. Docker, one-click, and Helm all bundle Cube by default; CUBEJS_API_SECRET is required. Operators can disable the bundled Cube deployment in Helm to use an external cluster instead.
Edge rate limiting is now required for specific public and API-key routes. Those routes are no longer throttled inside the application server.
AI features are configured at the instance level via AI_* environment variables.

Formbricks v5 removes application-level rate limiting for several routes that are now expected to be protected by Envoy Gateway or an equivalent edge rate limiter. If your self-hosted instance does not already have equivalent edge protection, add it before exposing the v5 stack.

Before You Upgrade

Before you restart your instance on Formbricks v5:

back up your database
identify your current deployment type: one-click, manual Docker Compose, or Kubernetes/Helm
confirm Redis/Valkey and your file storage setup are already healthy from your v4 baseline
identify whether file uploads use external S3-compatible storage or a legacy bundled MinIO service
budget approximately ~500 MB additional RAM headroom for the bundled Cube container (dashboards and analysis are part of the baseline now)
decide whether this instance needs optional AI features
verify whether you already run Envoy Gateway or another equivalent edge rate limiter for the covered routes

Required Config And Infrastructure Changes

Formbricks Hub

Formbricks v5 expects Hub to be part of the self-hosted stack.

HUB_API_KEY is required
HUB_API_URL must point to the Hub service the Formbricks app can reach
HUB_DATABASE_URL is optional; when unset, Hub can share the same PostgreSQL database as Formbricks
bundled Docker and Helm assets run Hub database migrations automatically during startup or upgrade, and the migration steps are idempotent

Hub-specific source code and standalone deployment assets live in the Formbricks Hub repository. For a normal Formbricks v5 upgrade, use that repository as reference material only; the canonical migration steps stay in these Formbricks docs.

Edge Rate Limiting

Formbricks v5 splits rate limiting across two layers:

Envoy Gateway, or an equivalent edge rate limiter, for covered public and API-key routes
the application server for the remaining session-authenticated routes, server actions, and uncovered APIs

Keep Redis/Valkey enabled for the remaining application-enforced limits. For the covered route groups and exact thresholds, use the rate-limiting guide as the source of truth.

AI Features

AI features are optional and only need instance-level configuration if you want to enable the related enterprise functionality.

AI_PROVIDER and AI_MODEL are the base settings
AI_PROVIDER=aws requires AI_AWS_REGION, AI_AWS_ACCESS_KEY_ID, and AI_AWS_SECRET_ACCESS_KEY
AI_PROVIDER=google requires AI_GOOGLE_CLOUD_PROJECT and AI_GOOGLE_CLOUD_LOCATION; credentials are optional overrides when Application Default Credentials are unavailable
AI_PROVIDER=azure requires AI_AZURE_API_KEY and either AI_AZURE_BASE_URL or AI_AZURE_RESOURCE_NAME
AI_PROVIDER=openai-compatible requires AI_OPENAI_COMPATIBLE_BASE_URL; the LLM GA v1 self-hosted path is Qwen served by vLLM
Helm operators can set llm.enabled: true to deploy the bundled Qwen/vLLM runtime
Docker Compose operators can set COMPOSE_PROFILES=qwen to deploy the bundled Qwen/vLLM runtime
Keep the bundled runtime disabled when you configure Google Vertex, Azure, AWS Bedrock, or an external OpenAI-compatible endpoint manually

Cube

Cube is part of the baseline Formbricks v5 stack.

the Docker, one-click, and Helm deployments all bundle the cube service by default
the Formbricks app requires CUBEJS_API_URL and CUBEJS_API_SECRET; the install/dev-setup scripts generate the secret automatically for new installs
Helm operators who want to run an external Cube cluster can set cube.enabled: false and provide their own endpoint via deployment.env.CUBEJS_API_URL
if you run Cube yourself, you may also need to override CUBEJS_DB_* values for the Cube service

Upgrade Steps By Deployment Type

1. Back up your database

One-Click
Docker Compose
Kubernetes

From the formbricks directory created by the installer:

cd formbricks
docker compose exec postgres pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v5_$(date +%Y%m%d_%H%M%S).dump

If your PostgreSQL service name differs, run docker compose ps first and adjust the command.

From the directory that contains your docker-compose.yml:

docker compose exec postgres pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v5_$(date +%Y%m%d_%H%M%S).dump

If your service is not named postgres, use docker compose ps to find the correct name.

If you are using the in-cluster PostgreSQL released by the Helm chart:

kubectl exec -n formbricks formbricks-postgresql-0 -- pg_dump -Fc -U formbricks -d formbricks > formbricks_pre_v5_$(date +%Y%m%d_%H%M%S).dump

If you use a managed PostgreSQL service, create a provider snapshot or run pg_dump directly against the external host before continuing.

2. Update your deployment config and restart on v5

One-Click
Docker Compose
Kubernetes

The one-click ./formbricks.sh update command only pulls new images. It does not rewrite your existing formbricks/docker-compose.yml, so you must merge the v5 stack changes before the first v5 restart.

curl -fsSL -o formbricks/docker-compose.v5.yml https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/docker-compose.yml

Then compare formbricks/docker-compose.v5.yml with your existing formbricks/docker-compose.yml and merge the v5 additions:

add a non-empty HUB_API_KEY and reuse the same value wherever your deployment resolves Hub auth
keep HUB_API_URL at http://hub:8080 unless Hub runs elsewhere
include the bundled formbricks-migrate, hub-migrate, and hub services
sync formbricks/cube/cube.js and formbricks/cube/schema/FeedbackRecords.js from the current release and ensure formbricks/.env contains CUBEJS_API_SECRET (Cube is part of the baseline stack in v5)
if your older setup still uses bundled MinIO for uploads, review that storage path separately before the first v5 restart; newer self-hosting updates move the bundled object-storage path to RustFS, while external S3-compatible storage keeps the same S3_* app contract
add any AI_* variables you need
if you prefer to run an external Cube instance, point CUBEJS_API_URL at it and provide the matching CUBEJS_API_SECRET; otherwise the bundled cube service runs against the local Postgres

After the compose file is updated and your edge rate limiter is in place:

./formbricks.sh update

Pull the current production compose file and merge the v5 changes into your existing deployment config before only updating images:

curl -fsSL -o docker-compose.v5.yml https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/docker-compose.yml

At minimum, confirm:

HUB_API_KEY is configured and the same value is available wherever your deployment resolves Hub auth
HUB_API_URL points to the Hub service the app can reach
the compose stack includes formbricks-migrate, hub-migrate, and hub
the v5 stack also includes cube, cube/cube.js, and cube/schema/FeedbackRecords.js, with CUBEJS_API_SECRET available through your .env or shell environment
if your legacy Compose file still includes bundled MinIO for uploads, treat that as a separate storage review when comparing files; newer bundled storage guidance uses RustFS, while external S3-compatible storage keeps the same S3_* app contract
any AI_* variables you need are set
if you prefer to run an external Cube instance, point CUBEJS_API_URL at it and supply the matching CUBEJS_API_SECRET; otherwise the bundled cube service runs against the local Postgres

Then restart the stack:

docker compose pull
docker compose down
docker compose up -d

The v5 Docker Compose stack bundles Hub and Cube. Keep the bundled cube/ config files in sync with docker-compose.yml when you update this path.

Upgrade using the current Formbricks chart:

helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \
  -n formbricks \
  -f values.yaml

Before running the upgrade, confirm these v5 expectations in your values:

keep hub.enabled=true; Hub is mandatory in v5
if you want the bundled Envoy path, configure envoy.enabled=true and then choose:
- envoy.controller.enabled=true for the bundled controller mode
- envoy.controller.enabled=false when the cluster already has a compatible Envoy Gateway controller
if you use bundled Envoy rate limiting, enable a dedicated backend with envoyRedis.enabled=true
if you already have an equivalent edge rate limiter outside the chart, keep that protection in place
CUBEJS_API_SECRET is provided (Cube is bundled by default at cube.enabled: true; set to false and point CUBEJS_API_URL at your own endpoint if you prefer an external Cube cluster)

Post-Upgrade Verification

After the upgrade:

confirm the Formbricks app starts and GET /health returns successfully
confirm the Hub service is healthy and reachable from the Formbricks app
verify any Hub-backed connector or feedback flows you use
verify covered routes are rate-limited at the edge layer
verify AI features only if you configured the required AI_* variables
verify dashboards and analysis flows against the bundled (or external) Cube endpoint

Troubleshooting And Rollback

Common upgrade issues:

Missing HUB_API_KEY: Formbricks cannot authenticate to Hub, and Hub itself may fail to start
Bad HUB_API_URL: the app starts, but Hub-backed features fail because the service cannot be reached
No edge rate limiter in front of covered routes: the v5 deployment runs, but those routes are no longer protected by the legacy in-app limiter
Missing AI provider configuration: AI features remain unavailable until AI_PROVIDER, AI_MODEL, and the matching provider settings are set correctly
Missing CUBEJS_API_SECRET (or unreachable Cube endpoint): the Formbricks app fails env validation at boot, or — if env vars are present but Cube is unreachable — dashboards and analysis queries fail while the rest of the app stays healthy
Cube healthcheck fails with wget: not found: older v5 Docker Compose files used wget for the bundled Cube healthcheck, but cubejs/cube:v1.6.6 does not include it. Sync the Cube healthcheck from the current Docker Compose file so it checks /readyz with Node instead.

If you need to roll back:

restore the pre-upgrade database backup if schema or data changes require it
revert your image tags or Helm release values to the last known-good Formbricks 4.x version
revert compose or Helm configuration changes introduced for the v5 rollout

Workspaces and Environment IDs Environment IDs were deprecated to simplify SDK setup around a single Workspace ID while keeping existing integrations backward compatible during migration. Website & App Surveys SDK: Migrate to Workspace ID

Formbricks v5 also includes the Environment ID to Workspace ID transition for SDK setup. If you still rely on a legacy Environment ID, read the Migrate to Workspace ID guide.

v4.7

Formbricks v4.7 introduces typed contact attributes with native number and date data types. This enables comparison-based segment filters (e.g. “signup date before 2025-01-01”) that were previously not possible with string-only attribute values.

What Happens Automatically

When Formbricks v4.7 starts for the first time, the data migration will:

Analyze all existing contact attribute keys and infer their data types (text, number, or date) based on the stored values
Update the ContactAttributeKey table with the detected dataType for each key
If your instance has fewer than 1,000,000 contact attribute rows: backfill the new valueNumber and valueDate columns inline. No manual action is needed.
If your instance has 1,000,000 or more contact attribute rows: the value backfill is skipped to avoid hitting the migration timeout. You will need to run a standalone backfill script after the upgrade.

Most self-hosted instances have far fewer than 1,000,000 contact attribute rows (a typical setup with 100K contacts and 5-10 attributes each lands around 500K-1M rows). If you are below the threshold, the migration handles everything automatically and you can skip the manual backfill step below.

Steps to Migrate

1. Backup your Database

Docker
Kubernetes

Before running these steps, navigate to the formbricks directory where your docker-compose.yml file is located.

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v4.7_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you are using the in-cluster PostgreSQL deployed by the Helm chart:

kubectl exec -n formbricks formbricks-postgresql-0 -- pg_dump -Fc -U formbricks -d formbricks > formbricks_pre_v4.7_$(date +%Y%m%d_%H%M%S).dump

If your PostgreSQL pod has a different name, run kubectl get pods -n formbricks to find it.

If you are using a managed PostgreSQL service (e.g. AWS RDS, Cloud SQL), use your provider’s backup/snapshot feature or run pg_dump directly against the external host.

2. Upgrade to Formbricks v4.7

Docker
Kubernetes

# Pull the latest version
docker compose pull

# Stop the current instance
docker compose down

# Start with Formbricks v4.7
docker compose up -d

helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \
  -n formbricks \
  --set deployment.image.tag=v4.7.0

The Helm chart includes a migration Job that automatically runs Prisma schema migrations as a PreSync hook before the new pods start. No manual migration step is needed.

3. Check the Migration Logs After Formbricks starts, check the logs to see whether the value backfill was completed or skipped:

Docker
Kubernetes

docker compose logs formbricks | grep -i "backfill"

# Check the application pod logs
kubectl logs -n formbricks -l app.kubernetes.io/name=formbricks --tail=200 | grep -i "backfill"

If the Helm migration Job ran, you can also inspect its logs:

kubectl logs -n formbricks job/formbricks-migration

If you see a message like Skipping value backfill (X rows >= 1000000 threshold), proceed to step 4. Otherwise, the migration is complete and no further action is needed. 4. Run the Backfill Script (large datasets only) If the migration skipped the value backfill, run the standalone backfill script inside the running Formbricks container:

Docker
Kubernetes

docker exec formbricks node packages/database/dist/scripts/backfill-attribute-values.js

Replace formbricks with your actual container name if it differs. Use docker ps to find it.

kubectl exec -n formbricks deploy/formbricks -- node packages/database/dist/scripts/backfill-attribute-values.js

If your Formbricks deployment has a different name, run kubectl get deploy -n formbricks to find it.

The script will output progress as it runs:

========================================
Attribute Value Backfill Script
========================================

Fetching number-type attribute keys...
Found 12 number-type keys. Backfilling valueNumber...
  Number backfill progress: 10/12 keys (48230 rows updated)
  Number backfill progress: 12/12 keys (52104 rows updated)

Fetching date-type attribute keys...
Found 5 date-type keys. Backfilling valueDate...
  Date backfill progress: 5/5 keys (31200 rows updated)

========================================
Backfill Complete!
========================================
  valueNumber rows updated: 52104
  valueDate rows updated:   31200
  Duration: 42.3s
========================================

Key characteristics of the backfill script:

Safe to run while Formbricks is live — it does not lock the entire table or wrap work in a long transaction
Idempotent — it only updates rows where the typed columns are still NULL, so you can safely run it multiple times
Resumable — each batch commits independently, so if the process is interrupted you can re-run it and it picks up where it left off
No timeout risk — unlike the migration, this script runs outside the migration transaction and has no time limit

5. Verify the Upgrade

Access your Formbricks instance at the same URL as before
If you use contact segments with number or date filters, verify they return the expected results
Check that existing surveys and response data are intact

v4.0

Important: Migration RequiredFormbricks 4 introduces additional requirements for self-hosting setups and makes a dedicated Redis cache as well as S3-compatible file storage mandatory.

Formbricks 4.0 is a major milestone that sets up the technical foundation for future iterations and feature improvements. This release focuses on modernizing core infrastructure components to improve reliability, scalability, and enable advanced features going forward.

What’s New in Formbricks 4.0

🚀 New Enterprise Features:

Quotas Management: Advanced quota controls for enterprise users

🏗️ Technical Foundation Improvements:

Enhanced File Storage: Improved file handling with better performance and reliability
Improved Caching: New caching functionality improving speed, extensibility and reliability
Database Optimization: Removal of unused database tables and fields for better performance
Future-Ready Architecture: Standardized infrastructure components for upcoming features

What This Means for Your Self-Hosting Setup

These improvements in Formbricks 4.0 also make some infrastructure requirements mandatory going forward:

Redis for caching
RustFS or S3-compatible storage for file uploads

These services are already included in the updated one-click setup for self-hosters, but existing users need to upgrade their setup. More information on this below.

Why We Made These Changes

We know this represents more moving parts in your infrastructure and might even introduce more complexity in hosting Formbricks, and we don’t take this decision lightly. As Formbricks grows into a comprehensive Survey and Experience Management platform, we’ve reached a point where the simple, single-service approach was holding back our ability to deliver the reliable, feature-rich product our users demand and deserve. By moving to dedicated, professional-grade services for these critical functions, we’re building the foundation needed to deliver:

Enterprise-grade reliability with proper redundancy and backup capabilities
Advanced features that require sophisticated caching and file processing
Better performance through optimized, dedicated services
Future scalability to support larger deployments and more complex use cases without the need to maintain two different approaches

We believe this is the only path forward to build the comprehensive Survey and Experience Management software we’re aiming for.

Migration Steps for v4.0

Additional migration steps are needed if you are using a self-hosted Formbricks setup that uses either local file storage (not S3-compatible file storage) or doesn’t already use a Redis cache.

Legacy one-click v4.0 upgrade

For historical v4.0 upgrades, our original one-click migration script is still available:

# Download the latest script
curl -fsSL -o migrate-to-v4.sh \
  https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/migrate-to-v4.sh

# Make it executable
chmod +x migrate-to-v4.sh

# Launch the guided migration
./migrate-to-v4.sh

This script guides you through the steps for the infrastructure migration and does the following:

Adds a Redis service to your setup and configures it
Adds a bundled MinIO service to your setup, configures it, and migrates local files to it
Pulls the latest Formbricks image and updates your instance

Manual Setup

If you use a different setup to host your Formbricks instance, you need to make sure to make the necessary adjustments to run Formbricks 4.0.

Redis

Formbricks 4.0 requires a Redis instance to work properly. Please add a Redis instance to your Docker setup, your K8s infrastructure, or however you are hosting Formbricks at the moment. Formbricks works with the latest versions of Redis as well as Valkey. You need to configure the REDIS_URL environment variable and point it to your Redis instance.

S3-compatible storage

To use file storage (e.g., file upload questions, image choice questions, custom survey backgrounds, etc.), you need to have S3-compatible file storage set up and connected to Formbricks. Formbricks supports multiple storage providers (among many other S3-compatible storages):

AWS S3
Digital Ocean Spaces
Hetzner Object Storage
Custom RustFS server

Please make sure to set up a storage bucket with one of these solutions and then link it to Formbricks using the following environment variables:

  S3_ACCESS_KEY: your-access-key
  S3_SECRET_KEY: your-secret-key
  S3_REGION: us-east-1
  S3_BUCKET_NAME: formbricks-uploads
  S3_ENDPOINT_URL: https://files.yourdomain.com # not needed for AWS S3
  S3_FORCE_PATH_STYLE: 1 # set this only for custom endpoints like RustFS, MinIO, or LocalStack; omit for AWS S3

Upgrade Process

1. Backup your Database Critical Step: Create a complete database backup before proceeding. Formbricks 4.0 will automatically remove unused database tables and fields during startup.

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v4.0_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

2. Upgrade to Formbricks 4.0 Pull the latest Docker images and restart the setup (example for docker-compose):

# Pull the latest version
docker compose pull

# Stop the current instance
docker compose down

# Start with Formbricks 4.0
docker compose up -d

3. Automatic Database Migration When you start Formbricks 4.0 for the first time, it will automatically:

Detect and apply required database schema updates
Remove unused database tables and fields
Optimize the database structure for better performance

No manual intervention is required for the database migration. 4. Verify Your Upgrade

Access your Formbricks instance at the same URL as before
Test file uploads to ensure S3 storage integration works correctly. Check the File Upload Troubleshooting section if you face any issues.
Verify that existing surveys and data are intact
Check that previously uploaded files are accessible

v3.3

With Formbricks 3.0, we introduced an automatic data migration system. If you’re using a version older than v2.7, you must upgrade step-by-step through earlier versions (e.g. 2.4 → 2.5 → 2.6 → 2.7). Once you reach v2.7, you can upgrade directly to any v3.x or future release without needing intermediate migrations.

Steps to Migrate

This guide is for users who are self-hosting Formbricks using the one-click setup. If you have a different setup, you may need to adjust the commands accordingly. Before running these steps, navigate to the formbricks directory where your docker-compose.yml file is located.

Backup your Database: Backing up your database is crucial before upgrading. Use the following command to create a backup:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.3_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

When you start the latest version of Formbricks, it will automatically detect and apply any required data migrations during startup. You don’t need to run any manual migration steps or download separate migration images.

Access your updated instance

Once the containers are running, simply go to the same URL as before to access your updated Formbricks instance. That’s it! This new process ensures your Formbricks setup stays up to date with the latest schema changes as soon as you run the updated container.

v3.2

Steps to Migrate

Backup your Database: Backing up your database is crucial before upgrading. Use the following command to create a backup:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.2_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Access your updated instance

v3.1

Steps to Migrate

Backup your Database: Backing up your database is crucial before upgrading. Use the following command to create a backup:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.1_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Access your updated instance

v3.0

Important: Do Not Upgrade to 3.0 If You Need SSO, User Identification, or Cluster SupportWith Formbricks 3.0, we’re making changes to ensure long-term sustainability while still supporting open source. While the Community Edition has gained new features, some advanced capabilities are now part of the Enterprise Edition.⚠️ No Downgrade Option: If you upgrade to 3.0 and run the data migration, you cannot revert to 2.7.2. If you rely on SSO, user identification, or cluster support, either stay on version 2.7.x or reach out to us on GitHub Discussions for a custom quote.

This major release brings a better approach to data migrations.

If you’re using Formbricks v2.7 or later, you can upgrade directly to v3.x and future versions.
If you’re on a version older than v2.7, you must upgrade step-by-step (e.g. 2.4 → 2.5 → 2.6 → 2.7) before moving to v3.x.

Steps to Migrate

This guide is for users self-hosting Formbricks with the one-click setup. If you’re using a different setup, you might adjust the commands.

Navigate to the Formbricks Directory

Before running any steps, go to the directory where your docker-compose.yml file is located.

Backup Your Database

Backing up your database is crucial before upgrading. Use the following command to create a backup:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.0_$(date +%Y%m%d_%H%M%S).dump

Note: If you see a “No such container” error, run docker ps to find your actual container name (e.g. formbricks_postgres_1).

Tip: If you want to store the backup as a .sql file, remove the -Fc (custom format) option. If you need to restore it later, use psql with an empty Formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

When you start the latest version of Formbricks, it will automatically detect and run any necessary data migrations during startup. There is no need to run any manual migration steps or pull any separate migration images.

Access your updated instance

That’s it! Once the containers are up and running, simply navigate to the same URL as before to access your fully migrated Formbricks instance.

v2.7

AI Features & Database Update: This release lays the groundwork for upcoming AI features, now in private beta. Formbricks requires the pgvector extension in PostgreSQL.One-Click Setup Users: Use the pgvector/pgvector:pg15 image instead of postgres:15-alpine to ensure compatibility.

Formbricks v2.7 includes all the features and improvements developed by the community during Hacktoberfest 2024. Additionally, this release introduces an advanced team-based access control system, which is available in the Formbricks Enterprise Edition.

Additional Updates

If you previously used organisation-based access control (an enterprise feature) and the DEFAULT_ORGANIZATION_ROLE environment variable, update its value to one of these roles: owner, manager, or member. Read more about the new roles in the documentation.

Steps to Migrate

This guide is for users who are self-hosting Formbricks using our one-click setup. If you are using a different setup, you might adjust the commands accordingly. To run all these steps, please navigate to the Formbricks folder where your docker-compose.yml file is located.

Backup your Database: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database.

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.7_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you want to store the backup as an *.sql file, remove the -Fc option. To restore, use psql with an empty Formbricks database.

If you use an older docker-compose.yml file from the one-click setup, modify it to use the pgvector/pgvector:pg15 image instead of postgres:15-alpine:

services:
  postgres:
    image: pgvector/pgvector:pg15
    volumes:
      - postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - 5432:5432

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance and remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find the Docker network name for your Postgres database, run docker network ls.

docker pull ghcr.io/formbricks/data-migrations:latest && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.7" \
  ghcr.io/formbricks/data-migrations:v2.7.0

The command above will migrate your data to the latest schema. This step is important to update your existing data to the new structure. The changes will only be made if the script runs successfully. You can run the script multiple times safely.

That’s it! Once the migration is finished, you can access your Formbricks instance at the same URL as before.

v2.6

Formbricks v2.6 introduces advanced logic jumps for surveys, allowing more complex branching logic, including variables, conditions, and more. This release also includes numerous bug fixes, significant performance improvements for website and app surveys, and enhanced stability.

This release includes the final step of deprecating server-side action tracking (previously used for segment filtering by performed actions). The migrations will delete all tracked actions from the database. If you still need these action records, ensure you export them before upgrading.

Steps to Migrate

This guide is for users who are self-hosting Formbricks using our one-click setup. If you’re using a different setup, you might need to adjust the commands accordingly. To run these steps, navigate to the folder where your docker-compose.yml file is located.

Backup your Database: This is an important step. Make sure to back up your database before proceeding with the upgrade. You can use this command to back up your database:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.6_$(date +%Y%m%d_%H%M%S).dump

If you get a “No such container” error, run docker ps to find your container name, for example, formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario, you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find the Docker network name for your Postgres database, run the command:

docker pull ghcr.io/formbricks/data-migrations:latest && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.6" \
  ghcr.io/formbricks/data-migrations:v2.6.0

The command above will migrate your data to the latest schema. This is an important step to update your existing data to the new structure. Changes will only be made if the script runs successfully. You can run the script multiple times without issues.

Once the migration is complete, you can access your Formbricks instance at the same URL as before.

v2.5

Formbricks v2.5 lets you visualise responses in a data table format. This release also brings a few bug fixes and performance improvements.

This release fixes the inconsistency of CTA and consent question values when a question is skipped. The value will now be set to an empty string instead of “dismissed” to maintain consistency with other questions.

Steps to Migrate

This guide is for users self-hosting Formbricks with our one-click setup. If you’re using a different setup, you may need to adjust the commands. To begin, navigate to the folder where your docker-compose.yml file is located.

Backup your Database: This step is important. Please make sure to back up your database before upgrading. You can use the following command to back up your database:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.5_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g.formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find your Docker Network name for your Postgres Database, find it using docker network ls

docker pull ghcr.io/formbricks/data-migrations:latest && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.5" \
  ghcr.io/formbricks/data-migrations:v2.5.3

The command will migrate your data to the latest schema, ensuring your existing data is updated to the new structure. Changes will only be made if the script runs successfully, and you can safely run the script multiple times.

Once the migration is complete, you can access your Formbricks instance at the same URL as before.

v2.4

Formbricks v2.4 lets you create multiple endings for your surveys and choose which one users see based on logic jumps. This version also includes bug fixes and performance improvements.

This release will remove support for advanced targeting (enterprise targeting for app surveys) using actions (e.g. targeting users who triggered action x 3 times in the last month). Actions can still be used as triggers, but they will no longer be stored on the server to improve Formbricks’ overall performance.

Steps to Migrate

This guide is for users who are self-hosting Formbricks with our one-click setup. If you’re using a different setup, you may need to adjust the commands accordingly. To follow these steps, go to the folder where your docker-compose.yml file is located.

Backup your Database: This step is important. Please make sure to back up your database before upgrading. You can use the following command to back up your database:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.4_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as a *.sql file, remove the -Fc (custom format) option. In case of a restore scenario, you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema: To find your Docker Network name for your Postgres Database, find it using docker network ls

docker pull ghcr.io/formbricks/data-migrations:v2.4.3 && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.4" \
  ghcr.io/formbricks/data-migrations:v2.4.3

The command above will migrate your data to the latest schema. This is an important step to update your data structure. Changes are only applied if the script runs successfully. You can run the script multiple times without issues.

That’s it! Once the migration is done, you can access your Formbricks instance at the same URL as before.

Additional Updates

The CRON_SECRET environment variable is now required to enhance the security of the internal cron APIs. Please ensure that this variable is set in your environment or docker-compose.yml. You can generate a secure secret using openssl rand -hex 32

v2.3

Formbricks v2.3 introduces new colour options for rating questions, enhanced multi-language support for Chinese (Simplified & Traditional), and includes several bug fixes and performance improvements.

Steps to Migrate

You only need to run the data migration if you have surveys set up in Chinese (zh). If you don’t have any surveys in Chinese, you can skip the migration step.

This guide is for users self-hosting Formbricks with our one-click setup. If you’re using a different setup, adjust the commands as needed. To proceed, go to the folder where your docker-compose.yml file is located.

Backup your Database: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.3_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find your Docker Network name for your Postgres Database, find it using docker network ls

docker pull ghcr.io/formbricks/data-migrations:v2.3.0 && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.3" \
  ghcr.io/formbricks/data-migrations:v2.3.0

The command above will migrate your data to the latest schema, which is essential for updating your data structure. Changes will only be made if the script runs successfully. You can safely run the script multiple times.

Once the migration is complete, you can access your Formbricks instance at the same URL as before.

Additional Updates

The feature to create short URLs in Formbricks is now deprecated. Existing short URLs will continue to work for now, but it is recommended to use long URLs instead. Support for short URL redirects will be removed in a future release.

v2.2

Formbricks v2.2 introduces XM research presets, providing a brand-new product onboarding experience. Our goal is to make user research “obviously easy” across different industries, starting with Software-as-a-Service and E-Commerce.

Steps to Migrate

This guide is for users who are self-hosting Formbricks with our one-click setup. If you’re using a different setup, you may need to adjust the commands accordingly. To run all these steps, please navigate to the formbricks folder where your docker-compose.yml file is located.

Backup your Database: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.2_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find your Docker Network name for your Postgres Database, find it using docker network ls

docker pull ghcr.io/formbricks/data-migrations:v2.2 && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.2" \
  ghcr.io/formbricks/data-migrations:v2.2

The command above will migrate your data to the latest schema. This is an important step to update your existing data. Changes will only be made if the script runs successfully. You can safely run the script multiple times.

Once the migration is complete, you can access your Formbricks instance at the same URL as before.

Changes in Environment Variables

The ONBOARDING_DISABLED environment variable is now deprecated. We have replaced the user onboarding with a product onboarding process that only runs when creating a new product.

v2.1

Formbricks v2.1 introduces more options for creating No-Code Actions and improves the self-hosting experience with a new onboarding process for fresh instances.

To improve the user experience and simplify setup for self-hosting instances, we are transitioning to a single organization model. This change allows self-hosts to manage their instance centrally and more easily control access. A new permissions system will also be introduced soon, providing more granular control over projects and resources within an organization.If you’ve previously created multiple organizations, you can still switch between them in the UI, but creating new organizations will no longer be possible.

Steps to Migrate

This guide is for users self-hosting Formbricks using our one-click setup. If you are using a different setup, you may need to adjust the commands accordingly. To follow these steps, please navigate to the Formbricks folder where your docker-compose.yml file is located.

Backup your Database: This is an essential step. Please ensure that you back up your database before proceeding with the upgrade. You can use the following command to back it up:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.1_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as a *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers.

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find your Docker network name for the Postgres database, run the following docker network ls

docker pull ghcr.io/formbricks/data-migrations:v2.1.0 && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.1" \
  ghcr.io/formbricks/data-migrations:v2.1.0

Once the migration script runs successfully, your data will be migrated to the latest schema. The script is designed to run safely multiple times, so you don’t need to worry if it’s executed more than once. After completing the migration, you can continue to access your Formbricks instance at the same URL as before.

That’s it! Once the migration is complete, you can now access your Formbricks instance at the same URL as before.

Changes in Environment Variables

SIGNUP_DISABLED is now deprecated. Self-hosting instances have signup disabled by default, and new users can only be invited by the organization owner or admin.
DEFAULT_TEAM_ID has been renamed to DEFAULT_ORGANIZATION_ID.
DEFAULT_TEAM_ROLE has been renamed to DEFAULT_ORGANIZATION_ROLE.

v2.0

Formbricks v2.0 introduces significant features such as Multi-Language Surveys and Advanced Styling for Surveys, aimed at improving the flexibility and appearance of your surveys. Additionally, the release includes several optimisations, bug fixes, and smaller improvements to ensure a smoother user experience. If you are upgrading to Formbricks v2.0, follow this guide to ensure a smooth migration of your existing Formbricks instance without encountering issues or build errors.

This upgrade requires a data migration. Please make sure to back up your database before proceeding. Follow the steps below to upgrade your Formbricks instance to v2.0.

If you’ve used the Formbricks Enterprise Edition with a free beta license key, your instance will be downgraded to the Community Edition 2.0. You can find all license details on the license page.

We are moving from DockerHub to GitHub Packages for our images. If you are still pulling the images from DockerHub please change image: formbricks/formbricks:latest to image:ghcr.io/formbricks/formbricks:latest in your docker-compose.yml file.

Steps to Migrate

This guide is for users who are self-hosting Formbricks using our one-click setup. If you are using a different setup, you might adjust the commands accordingly. To run all these steps, please navigate to the formbricks folder where your docker-compose.yml file is located.

Backup your Database: This is an essential step. Please ensure that you back up your database before proceeding with the upgrade. You can use the following command to back it up:

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.0_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as an *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Pull the latest version of Formbricks:

docker compose pull

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers with the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find your Docker Network name for your Postgres Database, find it using docker network ls

docker pull ghcr.io/formbricks/data-migrations:v2.0.3 && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.0" \
  ghcr.io/formbricks/data-migrations:v2.0.3

The above command will migrate your data to the latest schema. This is a crucial step to migrate your existing data to the new structure. Only if the script runs successful, changes are made to the database. The script can safely run multiple times.

That’s it! Once the migration is complete, you can now access your Formbricks instance at the same URL as before.

App Surveys with @formbricks/js

With this upgrade, we now dynamically fetch the package from our API endpoint and have updated the package entry points to support both app and website surveys. This ensures that you always have the latest version of the package (v2.0.0+). Old approach: (v1.6.5)

import formbricks from "@formbricks/js";

formbricks.init({
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  userId: "<user-id>", // optional
});

New approach: (v2.0.0) Website surveys:

import formbricks from "@formbricks/js/website";

formbricks.init({
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  // userId is not supported here
});

App surveys:

import formbricks from "@formbricks/js/app";

formbricks.init({
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  userId: "<user-id>", // required
});

v1.6

Formbricks v1.6 introduces key features like Advanced Targeting, Segmentation, on-the-fly survey triggers, and stability improvements. This update also changes some environment variables. Follow this guide to upgrade your Formbricks instance to v1.6 smoothly.

This upgrade requires a data migration. Ensure you back up your database before proceeding. Follow the steps below to upgrade your Formbricks instance to v1.6.

Steps to Migrate

This guide is for users self-hosting Formbricks with our one-click setup. If you’re using a different setup, adjust the commands accordingly. Navigate to the Formbricks folder containing your docker-compose.yml file to run the steps.

Backup your Database: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database:

docker exec formbricks-quickstart-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v1.6_$(date +%Y%m%d_%H%M%S).dump

If you run into “No such container”, use docker ps to find your container name, e.g. formbricks_postgres_1.

If you prefer storing the backup as a *.sql file remove the -Fc (custom format) option. In case of a restore scenario you will need to use psql then with an empty formbricks database.

Stop the running Formbricks instance & remove the related containers:

docker compose down

Restarting the containers will automatically pull the latest version of Formbricks:

docker compose up -d

Now let’s migrate the data to the latest schema:

To find your Docker Network name for your Postgres Database, find it using docker network ps

docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v1.6" \
  ghcr.io/formbricks/data-migrations:v1.6.1

That’s it! Once the migration is complete, you can now access your Formbricks instance at the same URL as before.

Restoring the database after a failed upgrade

docker exec -i formbricks-quickstart-postgres-1 pg_restore --clean -U postgres -v -d formbricks < formbricks_pre_v1.6_<timestamp_of_your_dump_file>.dump

Replace the path to formbricks_pre_v1.6_<timestamp_of_your_dump_file>.dump with the exact path to your .dump file.

This will wipe the database and restore from the .dump file.

App Surveys with `@formbricks/js`

If you’re using the @formbricks/js package, update it to version ~1.6.5 to access the latest features and improvements.

Currently, the package needs to be pinned to ~1.6.5, see this issue.

Upgrade and pin the client package

npm install @formbricks/js@~1.6.5

Deprecated Environment Variables

Environment Variable	Comments
`GITHUB_AUTH_ENABLED`	Was used to enable GitHub OAuth, but from v1.6, you can just set the `GITHUB_ID` and `GITHUB_SECRET` environment variables.
`GOOGLE_AUTH_ENABLED`	Was used to enable Google OAuth, but from v1.6, you can just set the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables.
`AZUREAD_AUTH_ENABLED`	Was used to enable AzureAD OAuth, but from v1.6, you can just set the `AZUREAD_CLIENT_ID`, `AZUREAD_CLIENT_SECRET` & `AZUREAD_TENANT_ID` environment variables.

v1.2

Formbricks v1.2 introduces new features for Link Surveys and enhances security. However, there are some breaking changes related to environment variables. This guide will help you upgrade your Formbricks instance to v1.2 smoothly.

New Environment Variables

Environment Variable	Required	Recommended Generation	Comments
`ENCRYPTION_KEY`	true	`openssl rand -hex 32`	Needed for 2 Factor Authentication

Deprecated / Removed Environment Variables

Environment Variable	Comments
`SURVEY_BASE_URL`	The `WEBAPP_URL` is now used to determine the survey base URL in all places

v1.1

Formbricks v1.1 introduces new features and improvements but includes breaking changes with environment variables. This guide will help you upgrade your Formbricks instance to v1.1 without data loss.

Renamed Environment Variables

till v1.0	v1.1
`NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLED`	`EMAIL_VERIFICATION_DISABLED`
`NEXT_PUBLIC_PASSWORD_RESET_DISABLED`	`PASSWORD_RESET_DISABLED`
`NEXT_PUBLIC_SIGNUP_DISABLED`	`SIGNUP_DISABLED`
`NEXT_PUBLIC_INVITE_DISABLED`	`INVITE_DISABLED`
`NEXT_PUBLIC_PRIVACY_URL`	`PRIVACY_URL`
`NEXT_PUBLIC_TERMS_URL`	`TERMS_URL`
`NEXT_PUBLIC_IMPRINT_URL`	`IMPRINT_URL`
`NEXT_PUBLIC_GITHUB_AUTH_ENABLED`	`GITHUB_AUTH_ENABLED`
`NEXT_PUBLIC_GOOGLE_AUTH_ENABLED`	`GOOGLE_AUTH_ENABLED`
`NEXT_PUBLIC_WEBAPP_URL`	`WEBAPP_URL`
`NEXT_PUBLIC_IS_FORMBRICKS_CLOUD`	`IS_FORMBRICKS_CLOUD`
`NEXT_PUBLIC_SURVEY_BASE_URL`	`SURVEY_BASE_URL`

Please note that their values and the logic remains exactly the same. Only the prefix has been deprecated. The other environment variables remain the same as well.

Deprecated Environment Variables

NEXT_PUBLIC_VERCEL_URL: Was used as deployment URL fallback (used instead of WEBAPP_URL), but from v1.1, you can just set the WEBAPP_URL environment variable.
RAILWAY_STATIC_URL: Was used as Railway Static URL (used instead of WEBAPP_URL), but from v1.1, you can just set the WEBAPP_URL environment variable.
RENDER_EXTERNAL_URL: Was used as an external URL to Render (used instead of WEBAPP_URL), but from v1.1, you can just set the WEBAPP_URL environment variable.
HEROKU_APP_NAME: Was used to build the App name on a Heroku hosted webapp, but from v1.1, you can just set the WEBAPP_URL environment variable.
NEXT_PUBLIC_WEBAPP_URL: Was used for the same purpose as WEBAPP_URL, but from v1.1, you can just set the WEBAPP_URL environment variable.
PRISMA_GENERATE_DATAPROXY: Was used to tell Prisma that it should generate the runtime for Dataproxy usage. But its officially deprecated now.

Helper Shell Script

For a seamless migration, below is a shell script for your self-hosted instance that will automatically update your environment variables to be compliant with the new naming conventions.

Docker & Single Script Setup

Now that these variables can be defined at runtime, you can append them inside your x-environment in the docker-compose.yml itself. For a more detailed guide on these environment variables, please refer to the Environment Variables page.

docker-compose.yml

version: "3.3"
x-environment: &environment
  environment:
    # The url of your Formbricks instance used in the admin panel
    WEBAPP_URL:

    # Required for next-auth. Should be the same as WEBAPP_URL
    NEXTAUTH_URL:

    # PostgreSQL DB for Formbricks to connect to
    DATABASE_URL: "postgresql://postgres:postgres@postgres:5432/formbricks?schema=public"

    # NextJS Auth
    # @see: https://next-auth.js.org/configuration/options#nextauth_secret
    # You can use: `openssl rand -hex 32` to generate one
    NEXTAUTH_SECRET:

    # PostgreSQL password
    POSTGRES_PASSWORD: postgres

    # Email Configuration
    MAIL_FROM:
    MAIL_FROM_NAME:
    SMTP_HOST:
    SMTP_PORT:
    SMTP_SECURE_ENABLED:
    SMTP_USER:
    SMTP_PASSWORD:

    # Uncomment the below and set it to 1 to disable Email Verification for new signups
    # EMAIL_VERIFICATION_DISABLED:

    # Uncomment the below and set it to 1 to disable Password Reset
    # PASSWORD_RESET_DISABLED:

    # Uncomment the below and set it to 1 to disable Signups
    # SIGNUP_DISABLED:

    # Uncomment the below and set it to 1 to disable loging in with email
    # EMAIL_AUTH_DISABLED:

    # Uncomment the below and set it to 1 to disable Invites
    # INVITE_DISABLED:

    # Uncomment the below and set a value to have your own Privacy Page URL on the signup & login page
    # PRIVACY_URL:

    # Uncomment the below and set a value to have your own Terms Page URL on the auth and the surveys page
    # TERMS_URL:

    # Uncomment the below and set a value to have your own Imprint Page URL on the auth and the surveys page
    # IMPRINT_URL:

    # Uncomment the below and set to 1 if you want to enable GitHub OAuth
    # GITHUB_AUTH_ENABLED:
    # GITHUB_ID:
    # GITHUB_SECRET:

    # Uncomment the below and set to 1 if you want to enable Google OAuth
    # GOOGLE_AUTH_ENABLED:
    # GOOGLE_CLIENT_ID:
    # GOOGLE_CLIENT_SECRET:

If you have any questions or require help, feel free to reach out to us on GitHub Discussions. 😃

​v5.2

​SSO Callback URL Change (action required for SSO users)

​Authentication Environment Variables

​Optional New Configuration

​Hub Enrichment (sentiment, emotion, translation)

​AI Taxonomy (beta)

​Bundled Qwen / vLLM Runtime

​OpenTelemetry Log Export

​Upgrade Steps

​Rollback

​v5

​What Changes In v5

​Before You Upgrade

​Required Config And Infrastructure Changes

​Formbricks Hub

​Edge Rate Limiting

​AI Features

​Cube

​Upgrade Steps By Deployment Type

​Post-Upgrade Verification

​Troubleshooting And Rollback

​v4.7

​What Happens Automatically

​Steps to Migrate

​v4.0

​What’s New in Formbricks 4.0

​What This Means for Your Self-Hosting Setup

​Why We Made These Changes

​Migration Steps for v4.0

​Legacy one-click v4.0 upgrade

​Manual Setup

​Redis

​S3-compatible storage

​Upgrade Process

​v3.3

​Steps to Migrate

​v3.2

​Steps to Migrate

​v3.1

​Steps to Migrate

​v3.0

​Steps to Migrate

​v2.7

​Additional Updates

​Steps to Migrate

​v2.6

​Steps to Migrate

​v2.5

​Steps to Migrate

​v2.4

​Steps to Migrate

​Additional Updates

​v2.3

​Steps to Migrate

​Additional Updates

​v2.2

​Steps to Migrate

​Changes in Environment Variables

​v2.1

​Steps to Migrate

​Changes in Environment Variables

​v2.0

​Steps to Migrate

​App Surveys with @formbricks/js

​v1.6

​Steps to Migrate

​Restoring the database after a failed upgrade

​App Surveys with @formbricks/js

​Upgrade and pin the client package

​Deprecated Environment Variables

​v1.2

​New Environment Variables

​Deprecated / Removed Environment Variables

​v1.1

​Renamed Environment Variables

​Deprecated Environment Variables

​Helper Shell Script

​Docker & Single Script Setup

v5.2

SSO Callback URL Change (action required for SSO users)

Authentication Environment Variables

Optional New Configuration

Hub Enrichment (sentiment, emotion, translation)

AI Taxonomy (beta)

Bundled Qwen / vLLM Runtime

OpenTelemetry Log Export

Upgrade Steps

Rollback

v5

What Changes In v5

Before You Upgrade

Required Config And Infrastructure Changes

Formbricks Hub

Edge Rate Limiting

AI Features

Cube

Upgrade Steps By Deployment Type

Post-Upgrade Verification

Troubleshooting And Rollback

v4.7

What Happens Automatically

Steps to Migrate

v4.0

What’s New in Formbricks 4.0

What This Means for Your Self-Hosting Setup

Why We Made These Changes

Migration Steps for v4.0

Legacy one-click v4.0 upgrade

Manual Setup

Redis

S3-compatible storage

Upgrade Process

v3.3

Steps to Migrate

v3.2

Steps to Migrate

v3.1

Steps to Migrate

v3.0

Steps to Migrate

v2.7

Additional Updates

Steps to Migrate

v2.6

Steps to Migrate

v2.5

Steps to Migrate

v2.4

Steps to Migrate

Additional Updates

v2.3

Steps to Migrate

Additional Updates

v2.2

Steps to Migrate

Changes in Environment Variables

v2.1

Steps to Migrate

Changes in Environment Variables

v2.0

Steps to Migrate

App Surveys with @formbricks/js

v1.6

Steps to Migrate

Restoring the database after a failed upgrade

App Surveys with `@formbricks/js`

Upgrade and pin the client package

Deprecated Environment Variables

v1.2

New Environment Variables

Deprecated / Removed Environment Variables

v1.1

Renamed Environment Variables

Deprecated Environment Variables

Helper Shell Script

Docker & Single Script Setup