Skip to main content
Use this guide for a manual Docker Compose setup. It downloads the production Compose file and starts the baseline Formbricks stack: Formbricks Web, PostgreSQL, Redis/Valkey, Formbricks Hub, and Cube. Optional services such as Qwen/vLLM, AI taxonomy, and RustFS are documented after the baseline stack is running. The baseline also runs a single SpiceDB instance for Formbricks authorization data. See deployment components for required services, managed alternatives and the release-specific image inventory.

Requirements

Make sure the following tools are installed:
  • Docker Engine with Docker Compose V2 (docker compose)
  • curl
  • openssl
  • A POSIX-compatible shell such as sh, bash, or zsh
Docker and Docker Compose are usually included in tools like Docker Desktop and Rancher Desktop.
docker compose without the hyphen is now the primary method of using docker-compose, according to the Docker documentation.

Choose Your Setup Path

  • Use this manual Docker Compose guide for local installs, custom servers, or custom reverse-proxy setups.
  • For a pre-provisioned SpiceDB database, complete External PostgreSQL for SpiceDB before validating or starting this stack.
  • Use the one-click setup script for Debian 12/13 or Ubuntu servers where you want Traefik, HTTPS certificates, and optional RustFS automation.
  • Use the migration guide before updating an existing Formbricks 4.x install or an older v5 compose file.
Starting with Formbricks v5, the production Docker Compose stack includes Formbricks Hub and Cube as part of the baseline. Keep HUB_API_URL at its internal default unless Hub runs elsewhere.

Start

  1. Create a New Directory for Formbricks Open a terminal and run the following commands to create and enter a new directory for Formbricks:
  2. Download the Docker Files Get the Docker Compose file, AuthZed database bootstrap helper, and Cube configuration shipped with the baseline stack:
    External SpiceDB PostgreSQL does not use the downloaded bootstrap helper; select its override below before starting the stack.
  3. Create the Environment File Store your configuration in .env. Docker Compose reads this file for variable interpolation, and the Formbricks container also loads it at startup. For a local install, use http://localhost:3000. For a server install, replace both URL values with your public HTTPS URL before starting the stack.
    Keep POSTGRES_PASSWORD unchanged after PostgreSQL initializes the postgres volume. The generated hexadecimal value is already URL-safe, so POSTGRES_PASSWORD_URL_ENCODED uses the same value. If you replace an existing docker-compose.yml, copy the exact password from that deployment instead of generating a new one. If it contains URI-reserved characters, set POSTGRES_PASSWORD_URL_ENCODED to its percent-encoded form; otherwise you can use the same value or omit the encoded variable. The PostgreSQL image only applies the raw password when it creates a new database volume.
  4. Validate the Docker Compose Configuration Validate the Compose file after .env contains the required values:
    If validation fails, check that .env contains the required values and that docker-compose.yml has valid syntax. In bundled mode, ensure AUTHZED_DATABASE_PASSWORD is non-empty; bootstrap also checks it before creating the SpiceDB database.
  5. Start the Docker Setup Now, you’re ready to run Formbricks with Docker. Use the command below to start Formbricks together with PostgreSQL, Redis, the Formbricks Hub API and worker, Cube, and SpiceDB.
    The -d flag runs the containers in the background, so they keep running even after you close the terminal.
  6. Verify the Stack Confirm the baseline services started and the Formbricks health endpoint responds:
    formbricks-migrate, hub-migrate, and spicedb-migrate should complete successfully; bundled mode also completes authzed-db-bootstrap, while external mode has no bootstrap service. postgres, redis, cube, hub, hub-worker, spicedb, and formbricks should be running or healthy. The worker has no HTTP health endpoint, so verify that it stays Up without repeated restarts.
  7. Open Formbricks in Your Browser Once the setup is running, open http://localhost:3000 in your browser to access Formbricks. The first time you visit, you’ll see a setup wizard. Follow the steps to create your first user and start using Formbricks.
The bundled Docker stack keeps Formbricks Hub and Cube internal to the compose network. The app reaches them through http://hub:8080 and http://cube:4000. When AI taxonomy beta is enabled, Hub reaches taxonomy internally through http://taxonomy:8000.

AuthZed and SpiceDB

The bundled SpiceDB service stores its data in a dedicated spicedb database and login inside the existing PostgreSQL container. Database bootstrap, datastore migration, and the release-matched authzed-initialize service are idempotent. Fresh installs apply the canonical schema and verify an empty or reconciled graph without making Formbricks startup or /health depend on SpiceDB. SpiceDB is reachable only inside the Compose network at spicedb:50051; it is not published on the host or routed through Traefik. The Formbricks container receives the supported AuthZed variables automatically. Keep AUTHZED_TOKEN and the bundled AUTHZED_DATABASE_PASSWORD private and include .env and the PostgreSQL volume in your backup plan. Running docker compose down preserves the volume; docker compose down -v deletes the bundled database volumes, but does not delete an external SpiceDB database.

External PostgreSQL for SpiceDB

Follow External PostgreSQL for SpiceDB before validating or starting the stack. Keep the same override for installation, maintenance and recovery. The release image includes an opt-in operations CLI. It does not start during normal installation:
See AuthZed Operations before applying a schema, repairing relationships, upgrading SpiceDB, or restoring a backup. The bundled PostgreSQL service leaves track_commit_timestamp at its default off value, so SpiceDB reports that its Watch API is disabled. This does not affect schema writes, relationship writes, or permission checks. If a future integration consumes the Watch API, enable that PostgreSQL setting separately and plan for the required database restart. Repository development exposes SpiceDB on 127.0.0.1:50051. To start the optional authenticated browser UI:
Then open http://127.0.0.1:50052. Run pnpm authzed:smoke for an isolated application-health, authentication-failure, bounded-outage, schema, permission, migration-idempotency, and persistence check. The smoke command uses its own Compose project and random host port, then removes its test data afterward. To check the developer stack through the Formbricks AuthZed client without writing data, run:
It reads the repository .env, prints one JSON result, and returns exit code 0 only when healthy. An empty SpiceDB schema is still a healthy connection. There is no AuthZed browser health page, and the normal Formbricks /health endpoint deliberately remains independent of SpiceDB. Restart Formbricks after changing any AUTHZED_* value.

Optional Services

Start and verify the baseline stack before enabling optional services.
If .env already contains a COMPOSE_PROFILES line, update that line instead of adding a second one.

Optional AI services

See AI deployment options for this deployment method, and AI configuration for providers and credentials.

Update

To upgrade, start with Upgrade Formbricks, then follow the Docker Compose runbook. To add SpiceDB to an existing installation for 6.0, see the 6.0 setup steps.

IPv6 visitors

If a container in this Compose project publishes the ports visitors connect to over IPv6, such as a reverse proxy you added, give the network IPv6. Otherwise Docker hands those connections to the container from its bridge gateway, and Formbricks sees every IPv6 visitor as that one address, for rate limiting and in logs. With Docker Engine 27.0 or later and IPv6 on the host, add this to docker-compose.yml:
Then recreate the network with docker compose down and docker compose up -d. The one-click setup adds this for you. A reverse proxy that runs on the host itself and forwards to 127.0.0.1:3000 does not need it.

Optional storage

Choose a provider in file uploads. For the bundled option, use RustFS with Docker.

Debug

If startup fails, first check the resolved configuration and container state:
Then inspect the services that commonly explain startup issues:
Common checks:
  • Missing or empty secrets: Confirm .env contains BETTER_AUTH_SECRET, ENCRYPTION_KEY, CRON_SECRET, HUB_API_KEY, and CUBEJS_API_SECRET.
  • Migration failures: Check formbricks-migrate, hub-migrate, and postgres logs. Do not remove Docker volumes on an existing install unless you intend to delete its data. For a failed formbricks-migrate, follow If a migration fails.
  • Cube is unhealthy: Confirm cube/cube.js, cube/schema/FeedbackRecords.js, and CUBEJS_API_SECRET exist, then inspect docker compose logs cube.
  • Hub auth errors: Confirm the same HUB_API_KEY from .env is used by Formbricks Web and the Hub service.
  • Hub jobs remain queued: Confirm docker compose ps hub-worker reports Up, then inspect docker compose logs --tail=200 hub-worker. The worker has no HTTP health endpoint; a stable process and a shrinking River backlog are its readiness signals. If it restarts, confirm each configured enrichment provider/model has the required credentials and that the worker can reach PostgreSQL.
  • Port conflicts: Confirm port 3000 and any optional service ports you enabled are not already in use on the host. The current template does not publish the bundled Valkey (redis service) to the host — it is reachable only on the internal compose network — so a fresh install does not need port 6379 free on the host.
  • Optional Qwen/vLLM issues: Check GPU availability, NVIDIA Container Toolkit installation, and docker compose --profile qwen logs --tail=200 vllm.
Existing installs: remove the bundled Valkey host port. Older templates published the redis (Valkey) service on 0.0.0.0:6379 with no password. That instance stores Better Auth sessions and verification tokens, so an exposed port lets anyone who can reach it read live sessions and take over accounts. Updating Formbricks (docker compose pull / up -d) does not rewrite your existing docker-compose.yml, so the mapping stays until you remove it. Open your docker-compose.yml, delete the
lines from the redis: service, then run docker compose up -d. The app reaches Valkey over the internal compose network, so no other configuration change is needed. Only keep a publish if an external tool genuinely needs it, and then bind it to loopback (127.0.0.1:6379:6379) rather than all interfaces.If the port was reachable from an untrusted network, also invalidate existing sessions. Valkey persists to its redis volume, so removing the port does not clear session or token state an attacker may already have written — a forged session can remain valid afterward. After closing the port, set a new BETTER_AUTH_SECRET in your .env, then recreate the app container so it picks up the change:
A plain docker compose restart keeps the container’s original environment, so the rotated secret would not take effect. Recreating invalidates every session cookie, so all users must sign in again, while stored data, the job queue, and the cache stay intact. (On an instance installed before this variable was renamed, the secret may live in your .env under the older name, NEXTAUTH_SECRET. Replace the value of whichever name your .env actually defines. Adding the other name alongside it does not reliably rotate anything: BETTER_AUTH_SECRET wins whenever both are set, so a new NEXTAUTH_SECRET next to an existing BETTER_AUTH_SECRET changes nothing and leaves the forged session valid.) Leave ENCRYPTION_KEY unchanged, and do not run a blanket FLUSHDB — the same Valkey also holds BullMQ job queues and the application cache.
To edit any of the available environment variables, check out our Configuration section.
If you have any questions or require help, reach out on GitHub Discussions.

Verify the installation

Run the deployment check in a dedicated workspace before collecting real responses.