Requirements
Make sure the following tools are installed:- Docker Engine with Docker Compose V2 (
docker compose) curlopenssl- A POSIX-compatible shell such as
sh,bash, orzsh
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
-
Create a New Directory for Formbricks
Open a terminal and run the following commands to create and enter a new directory for Formbricks:
-
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.
-
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, usehttp://localhost:3000. For a server install, replace both URL values with your public HTTPS URL before starting the stack.KeepPOSTGRES_PASSWORDunchanged after PostgreSQL initializes thepostgresvolume. The generated hexadecimal value is already URL-safe, soPOSTGRES_PASSWORD_URL_ENCODEDuses the same value. If you replace an existingdocker-compose.yml, copy the exact password from that deployment instead of generating a new one. If it contains URI-reserved characters, setPOSTGRES_PASSWORD_URL_ENCODEDto 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. -
Validate the Docker Compose Configuration
Validate the Compose file after
.envcontains the required values:If validation fails, check that.envcontains the required values and thatdocker-compose.ymlhas valid syntax. In bundled mode, ensureAUTHZED_DATABASE_PASSWORDis non-empty; bootstrap also checks it before creating the SpiceDB database. -
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
-dflag runs the containers in the background, so they keep running even after you close the terminal. -
Verify the Stack
Confirm the baseline services started and the Formbricks health endpoint responds:
formbricks-migrate,hub-migrate, andspicedb-migrateshould complete successfully; bundled mode also completesauthzed-db-bootstrap, while external mode has no bootstrap service.postgres,redis,cube,hub,hub-worker,spicedb, andformbricksshould be running or healthy. The worker has no HTTP health endpoint, so verify that it staysUpwithout repeated restarts. - 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 dedicatedspicedb 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: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:
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:
.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 todocker-compose.yml:
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:- Missing or empty secrets: Confirm
.envcontainsBETTER_AUTH_SECRET,ENCRYPTION_KEY,CRON_SECRET,HUB_API_KEY, andCUBEJS_API_SECRET. - Migration failures: Check
formbricks-migrate,hub-migrate, andpostgreslogs. Do not remove Docker volumes on an existing install unless you intend to delete its data. For a failedformbricks-migrate, follow If a migration fails. - Cube is unhealthy: Confirm
cube/cube.js,cube/schema/FeedbackRecords.js, andCUBEJS_API_SECRETexist, then inspectdocker compose logs cube. - Hub auth errors: Confirm the same
HUB_API_KEYfrom.envis used by Formbricks Web and the Hub service. - Hub jobs remain queued: Confirm
docker compose ps hub-workerreportsUp, then inspectdocker 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
3000and any optional service ports you enabled are not already in use on the host. The current template does not publish the bundled Valkey (redisservice) to the host — it is reachable only on the internal compose network — so a fresh install does not need port6379free on the host. - Optional Qwen/vLLM issues: Check GPU availability, NVIDIA Container Toolkit installation, and
docker compose --profile qwen logs --tail=200 vllm.
To edit any of the available environment variables, check out our
Configuration section.