Skip to main content

​
Custom Configurations

These variables are present inside your machine’s docker-compose file. Restart the docker containers if you change any variables for them to take effect.
Upgrading from Formbricks 4.x to 5.0? Read the migration guide first. Formbricks v5 makes Hub part of the standard self-hosted runtime and changes how rate limiting is enforced.
For the AI_* variables, see AI Features — it walks through each provider and the credentials it needs. Set only the variables for the provider you use; unused provider variables can be omitted.

​
OAuth and MCP URLs

The MCP server is available on the private/admin app at /api/mcp. OAuth discovery and token issuance are also private/admin app surfaces:
If you use a custom subpath, include that subpath in WEBAPP_URL, NEXTAUTH_URL, and BETTER_AUTH_URL if set. Do not point MCP or OAuth clients at PUBLIC_URL; that domain is reserved for public survey delivery and SDK traffic.

​
Formbricks Hub

Starting with Formbricks v5, Hub is part of the standard self-hosted runtime. When you run Formbricks with the bundled Docker Compose or Helm assets, the following variables apply:

​
AuthZed / SpiceDB Authorization

These variables define the supported authorization-client contract. Formbricks v6 enables AuthZed by default for fresh Docker, one-click, and Helm installations. Existing installations must pass the release-matched upgrade gate before enabling the v6 application image. Docker Compose additionally requires AUTHZED_DATABASE_PASSWORD for its dedicated spicedb PostgreSQL login. Generate both it and AUTHZED_TOKEN with openssl rand -hex 32. SPICEDB_IMAGE_REF can override the bundled authzed/spicedb:v1.52.0 image for an explicitly reviewed upgrade; the migration and server services always use the same reference. AUTHZED_ENABLED and AUTHZED_INSECURE accept true, false, 1, or 0. When AUTHZED_ENABLED is unset, the application client is disabled; when AUTHZED_INSECURE is unset, it uses TLS. A configured endpoint must be a bare host:port with an explicit port from 1 through 65535, for example spicedb:50051, grpc.authzed.com:443, or [::1]:50051. Do not include a URL scheme, path, query, credentials, or whitespace. AUTHZED_SYSTEM_KEY must be a 3–64 character lowercase SpiceDB identifier made from letters, digits, and underscores; it must start with a letter or underscore and end with a letter or digit. The supported consistency values are minimize_latency and fully_consistent. Released v6 Docker and Helm deployments require fully_consistent; the upgrade gate rejects weaker consistency. Valid endpoint, token, and system-key values may be set before enabling AuthZed. Invalid supplied values are rejected even while it is disabled. Changing any AuthZed setting requires restarting the Formbricks process. Configuration validation never prints the token. In a released Docker installation, validate the configured connection without installing a schema or changing data:
For Helm, run formbricks-authzed health inside a Formbricks application pod. Repository development can keep using pnpm authzed:health. See AuthZed Operations for the complete Docker and Kubernetes command set, schema lifecycle, backups, and relationship repair. Only the repository-development pnpm authzed:health command reads the repository .env. Docker Compose uses the authzed-ops container environment, while Helm and Kubernetes use the Formbricks Pod environment. Each invocation performs an authenticated read-only schema request, prints exactly one JSON result, and exits 0 only for {"status":"healthy","latencyMs":12} (the latency varies). Disabled or failed checks exit 1. Failures use stable codes: authzed_unauthenticated or authzed_permission_denied for rejected credentials or schema-read access (the bundled SpiceDB preshared-key check reports a wrong token as permission denied), authzed_timeout when an attempt exceeds its deadline, authzed_overloaded when SpiceDB is resource constrained, authzed_unavailable when the service cannot be reached, and authzed_internal for an unexpected client failure. Schema text, tokens, raw SDK errors, and stack traces are never included. This check is intentionally a CLI rather than a browser page or HTTP endpoint. AuthZed is not part of the general /health response, Kubernetes readiness, or application startup, so a transient SpiceDB outage does not restart or mark the rest of Formbricks unhealthy. Failed or unavailable permission checks fail the protected operation closed; there is no runtime fallback to legacy authorization. Existing installations must complete formbricks-authzed upgrade prepare followed by upgrade check before upgrading. The general application readiness probe remains independent from AuthZed so a transient authorization outage does not restart unrelated Formbricks workloads.

​
Cube Analytics

Cube is part of the baseline Formbricks v5 stack and is required. Formbricks generates the backend Cube JWT from CUBEJS_API_SECRET, so CUBEJS_API_TOKEN is not part of the supported setup contract. The bundled Docker Compose Cube service sets CUBEJS_DEFAULT_API_SCOPES=meta,data directly on the Cube container. If you run Cube outside the bundled Compose stack, configure the equivalent Cube service environment there rather than adding it to the Formbricks app environment. For Helm deployments, the chart deploys Cube by default (cube.enabled: true). To use an external Cube cluster instead, set cube.enabled: false, point CUBEJS_API_URL at your endpoint, and supply CUBEJS_API_SECRET through your existing secret management setup. Note: If you want to configure something that is not possible via above, please open an issue on our GitHub repo here or reach out to us on Github Discussions and we’ll try our best to work out a solution with you.