> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Environment variables for Formbricks

#### 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.

<Note>
  Upgrading from Formbricks 4.x to 5.0? Read the [migration guide](/docs/self-hosting/advanced/migration#v5) first.
  Formbricks v5 makes Hub part of the standard self-hosted runtime and changes how rate limiting is enforced.
</Note>

For the `AI_*` variables, see [AI Features](/docs/self-hosting/advanced/enterprise-features/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.

| Variable                                                                                       | Description                                                                                                                                                                                                                                                                                                                                 | Required                                                                           | Default                                                                   |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| WEBAPP\_URL                                                                                    | Base URL of the private/admin Formbricks app. OAuth and MCP protected-resource URLs are derived from this value.                                                                                                                                                                                                                            | required                                                                           | [http://localhost:3000](http://localhost:3000)                            |
| PUBLIC\_URL                                                                                    | Base URL for the public domain where surveys and public-facing content are served. If not set, uses WEBAPP\_URL. OAuth and MCP do not use PUBLIC\_URL.                                                                                                                                                                                      | optional                                                                           | WEBAPP\_URL                                                               |
| NEXTAUTH\_URL                                                                                  | Legacy-compatible auth base URL. This should normally be the same as WEBAPP\_URL; Formbricks derives the Better Auth issuer under `/api/auth`.                                                                                                                                                                                              | required                                                                           | [http://localhost:3000](http://localhost:3000)                            |
| BETTER\_AUTH\_URL                                                                              | Optional Better Auth base URL override. Set this only when the auth server base differs from NEXTAUTH\_URL; preserve any custom subpath.                                                                                                                                                                                                    | optional                                                                           | NEXTAUTH\_URL                                                             |
| MCP\_OAUTH\_JWKS\_URL                                                                          | Optional server-only URL used to fetch Better Auth signing keys for MCP OAuth. It does not change the public issuer, redirects, cookies, or token audience. Docker Compose and Helm leave it unset unless explicitly configured. Use an internal HTTP URL only on a trusted application network and include any custom application subpath. | optional                                                                           | `{BETTER_AUTH_URL or NEXTAUTH_URL}/jwks`                                  |
| DATABASE\_URL                                                                                  | Database URL with credentials.                                                                                                                                                                                                                                                                                                              | required                                                                           |                                                                           |
| NEXTAUTH\_SECRET                                                                               | Secret for NextAuth, used for session signing and encryption.                                                                                                                                                                                                                                                                               | required                                                                           | (Generated by the user, must not exceed 32 bytes, `openssl rand -hex 32`) |
| BETTER\_AUTH\_SECRET                                                                           | Optional Better Auth secret override. If unset, Formbricks uses NEXTAUTH\_SECRET for Better Auth session signing.                                                                                                                                                                                                                           | optional                                                                           | NEXTAUTH\_SECRET                                                          |
| ENCRYPTION\_KEY                                                                                | Secret used by Formbricks for data encryption and audit log hashing.                                                                                                                                                                                                                                                                        | required                                                                           | (Generated by the user, must not exceed 32 bytes, `openssl rand -hex 32`) |
| CRON\_SECRET                                                                                   | API Secret for running cron jobs.                                                                                                                                                                                                                                                                                                           | required                                                                           | (Generated by the user, must not exceed 32 bytes, `openssl rand -hex 32`) |
| LOG\_LEVEL                                                                                     | Minimum log level (debug, info, warn, error, fatal)                                                                                                                                                                                                                                                                                         | optional                                                                           | info                                                                      |
| S3\_ACCESS\_KEY                                                                                | Access key for S3.                                                                                                                                                                                                                                                                                                                          | optional                                                                           | (resolved by the AWS SDK)                                                 |
| S3\_SECRET\_KEY                                                                                | Secret key for S3.                                                                                                                                                                                                                                                                                                                          | optional                                                                           | (resolved by the AWS SDK)                                                 |
| S3\_REGION                                                                                     | Region for S3.                                                                                                                                                                                                                                                                                                                              | optional                                                                           | (resolved by the AWS SDK)                                                 |
| S3\_BUCKET\_NAME                                                                               | S3 bucket name for data storage. Formbricks enables S3 storage when this is set.                                                                                                                                                                                                                                                            | optional (required if S3 is enabled)                                               |                                                                           |
| S3\_ENDPOINT\_URL                                                                              | Endpoint for S3.                                                                                                                                                                                                                                                                                                                            | optional                                                                           | (resolved by the AWS SDK)                                                 |
| S3\_FORCE\_PATH\_STYLE                                                                         | Set to `1` to force path-style S3 URLs. Required for S3-compatible storage (MinIO, RustFS, LocalStack). Leave unset or `0` for standard AWS S3.                                                                                                                                                                                             | optional                                                                           | 0                                                                         |
| SAML\_DATABASE\_URL                                                                            | Database URL for SAML.                                                                                                                                                                                                                                                                                                                      | optional                                                                           | postgres\://postgres:@localhost:5432/formbricks-saml                      |
| PRIVACY\_URL                                                                                   | URL for privacy policy.                                                                                                                                                                                                                                                                                                                     | optional                                                                           |                                                                           |
| TERMS\_URL                                                                                     | URL for terms of service.                                                                                                                                                                                                                                                                                                                   | optional                                                                           |                                                                           |
| IMPRINT\_URL                                                                                   | URL for imprint.                                                                                                                                                                                                                                                                                                                            | optional                                                                           |                                                                           |
| IMPRINT\_ADDRESS                                                                               | Address for imprint.                                                                                                                                                                                                                                                                                                                        | optional                                                                           |                                                                           |
| EMAIL\_AUTH\_DISABLED                                                                          | Disables the ability for users to signup or login via email and password if set to 1.                                                                                                                                                                                                                                                       | optional                                                                           |                                                                           |
| PASSWORD\_RESET\_DISABLED                                                                      | Disables password reset functionality if set to 1.                                                                                                                                                                                                                                                                                          | optional                                                                           |                                                                           |
| PASSWORD\_HIBP\_CHECK\_DISABLED                                                                | Disables the Have-I-Been-Pwned breach check on password set (signup / reset) if set to 1. The check calls api.pwnedpasswords.com and fails open on network errors; set this on air-gapped / closed-network deployments to skip the outbound call.                                                                                           | optional                                                                           |                                                                           |
| PASSWORD\_RESET\_TOKEN\_LIFETIME\_MINUTES                                                      | Configures how long password reset links remain valid in minutes. Accepted values are integers from 5 to 120.                                                                                                                                                                                                                               | optional                                                                           | 30                                                                        |
| EMAIL\_VERIFICATION\_DISABLED                                                                  | Disables email verification if set to 1.                                                                                                                                                                                                                                                                                                    | optional                                                                           |                                                                           |
| RATE\_LIMITING\_DISABLED                                                                       | Disables only the application-level rate limiter if set to 1. It does not disable Envoy or an equivalent edge rate limiter.                                                                                                                                                                                                                 | optional                                                                           |                                                                           |
| INVITE\_RATE\_LIMIT\_PER\_24\_HOURS                                                            | Maximum invite recipients one organization may target across single, bulk, onboarding, and resend flows within 24 hours.                                                                                                                                                                                                                    | optional                                                                           | 50                                                                        |
| ENTERPRISE\_LICENSE\_KEY                                                                       | License key for the Formbricks Enterprise Edition. Unlocks Enterprise-only features; the instance validates it against the Formbricks license server, so it needs outbound network access (or `HTTP_PROXY`/`HTTPS_PROXY`). See [License Activation](/docs/self-hosting/advanced/license-activation).                                             | optional (required for Enterprise Edition features)                                |                                                                           |
| TELEMETRY\_DISABLED                                                                            | Disables telemetry reporting if set to 1. Ignored when an Enterprise License is active.                                                                                                                                                                                                                                                     | optional                                                                           |                                                                           |
| DANGEROUSLY\_ALLOW\_WEBHOOK\_INTERNAL\_URLS                                                    | Allows webhook URLs to point to internal/private network addresses (e.g. localhost, 192.168.x.x) if set to 1. Useful for self-hosted instances that need to send webhooks to internal services.                                                                                                                                             | optional                                                                           |                                                                           |
| INVITE\_DISABLED                                                                               | Disables the ability for invited users to create an account if set to 1.                                                                                                                                                                                                                                                                    | optional                                                                           |                                                                           |
| MAIL\_FROM                                                                                     | Email address to send emails from.                                                                                                                                                                                                                                                                                                          | optional (required if email services are to be enabled)                            |                                                                           |
| MAIL\_FROM\_NAME                                                                               | Email name/title to send emails from.                                                                                                                                                                                                                                                                                                       | optional (required if email services are to be enabled)                            |                                                                           |
| SMTP\_HOST                                                                                     | Host URL of your SMTP server.                                                                                                                                                                                                                                                                                                               | optional (required if email services are to be enabled)                            |                                                                           |
| SMTP\_PORT                                                                                     | Host Port of your SMTP server.                                                                                                                                                                                                                                                                                                              | optional (required if email services are to be enabled)                            |                                                                           |
| SMTP\_USER                                                                                     | Username for your SMTP Server.                                                                                                                                                                                                                                                                                                              | optional (required if email services are to be enabled)                            |                                                                           |
| SMTP\_PASSWORD                                                                                 | Password for your SMTP Server.                                                                                                                                                                                                                                                                                                              | optional (required if email services are to be enabled)                            |                                                                           |
| SMTP\_AUTHENTICATED                                                                            | If set to 0, the server will not require SMTP\_USER and SMTP\_PASSWORD(default is 1)                                                                                                                                                                                                                                                        | optional                                                                           |                                                                           |
| SMTP\_SECURE\_ENABLED                                                                          | SMTP secure connection. For using TLS, set to 1 else to 0.                                                                                                                                                                                                                                                                                  | optional (required if email services are to be enabled)                            |                                                                           |
| SMTP\_REJECT\_UNAUTHORIZED\_TLS                                                                | Keep at `1` to verify the SMTP server certificate. Setting `0` disables certificate verification and is unsafe for production; mount a private CA and configure `NODE_EXTRA_CA_CERTS` instead.                                                                                                                                              | optional                                                                           | 1                                                                         |
| TURNSTILE\_SITE\_KEY                                                                           | Site key for Turnstile.                                                                                                                                                                                                                                                                                                                     | optional                                                                           |                                                                           |
| TURNSTILE\_SECRET\_KEY                                                                         | Secret key for Turnstile.                                                                                                                                                                                                                                                                                                                   | optional                                                                           |                                                                           |
| RECAPTCHA\_SITE\_KEY                                                                           | Site key for survey responses recaptcha bot protection                                                                                                                                                                                                                                                                                      | optional                                                                           |                                                                           |
| RECAPTCHA\_SECRET\_KEY                                                                         | Secret key for recaptcha bot protection.                                                                                                                                                                                                                                                                                                    | optional                                                                           |                                                                           |
| GITHUB\_ID                                                                                     | Client ID for GitHub.                                                                                                                                                                                                                                                                                                                       | optional (required if GitHub auth is enabled)                                      |                                                                           |
| GITHUB\_SECRET                                                                                 | Secret for GitHub.                                                                                                                                                                                                                                                                                                                          | optional (required if GitHub auth is enabled)                                      |                                                                           |
| GOOGLE\_CLIENT\_ID                                                                             | Client ID for Google.                                                                                                                                                                                                                                                                                                                       | optional (required if Google auth is enabled)                                      |                                                                           |
| GOOGLE\_CLIENT\_SECRET                                                                         | Secret for Google.                                                                                                                                                                                                                                                                                                                          | optional (required if Google auth is enabled)                                      |                                                                           |
| AI\_PROVIDER                                                                                   | Instance-level AI provider used in the background. Supported values: `aws`, `google`, `azure`, `openai-compatible`.                                                                                                                                                                                                                         | optional (required if AI is enabled)                                               |                                                                           |
| AI\_MODEL                                                                                      | Instance-level AI model or deployment name used by the active provider.                                                                                                                                                                                                                                                                     | optional (required if `AI_PROVIDER` is set)                                        |                                                                           |
| AI\_GOOGLE\_CLOUD\_PROJECT                                                                     | Google Cloud project ID for the `google` AI provider.                                                                                                                                                                                                                                                                                       | optional (required if `AI_PROVIDER=google`)                                        |                                                                           |
| AI\_GOOGLE\_CLOUD\_LOCATION                                                                    | Google Cloud location for `google` AI requests. Passed through as given; `us` and `eu` use multi-region endpoints. `global` is the safe default.                                                                                                                                                                                            | optional (required if `AI_PROVIDER=google`)                                        |                                                                           |
| AI\_GOOGLE\_CLOUD\_CREDENTIALS\_JSON                                                           | Optional service account credentials JSON override for the `google` AI provider. Omit when Application Default Credentials are available.                                                                                                                                                                                                   | optional                                                                           |                                                                           |
| AI\_GOOGLE\_CLOUD\_APPLICATION\_CREDENTIALS                                                    | Optional path to Google Application Default Credentials used by the `google` AI provider.                                                                                                                                                                                                                                                   | optional                                                                           |                                                                           |
| AI\_AWS\_REGION                                                                                | AWS region for Amazon Bedrock.                                                                                                                                                                                                                                                                                                              | optional (required if `AI_PROVIDER=aws`)                                           |                                                                           |
| AI\_AWS\_ACCESS\_KEY\_ID                                                                       | AWS access key ID for Amazon Bedrock.                                                                                                                                                                                                                                                                                                       | optional (required if `AI_PROVIDER=aws`)                                           |                                                                           |
| AI\_AWS\_SECRET\_ACCESS\_KEY                                                                   | AWS secret access key for Amazon Bedrock.                                                                                                                                                                                                                                                                                                   | optional (required if `AI_PROVIDER=aws`)                                           |                                                                           |
| AI\_AWS\_SESSION\_TOKEN                                                                        | AWS session token for Amazon Bedrock temporary credentials.                                                                                                                                                                                                                                                                                 | optional                                                                           |                                                                           |
| AI\_AZURE\_BASE\_URL                                                                           | Azure OpenAI / Foundry base URL, ending at `/openai` — the SDK appends `/v1` itself. When set, this is preferred over `AI_AZURE_RESOURCE_NAME`.                                                                                                                                                                                             | optional (one of this or `AI_AZURE_RESOURCE_NAME` required if `AI_PROVIDER=azure`) |                                                                           |
| AI\_AZURE\_RESOURCE\_NAME                                                                      | Azure resource name used to assemble the Azure OpenAI URL.                                                                                                                                                                                                                                                                                  | optional (one of this or `AI_AZURE_BASE_URL` required if `AI_PROVIDER=azure`)      |                                                                           |
| AI\_AZURE\_API\_KEY                                                                            | API key for Azure OpenAI / Foundry.                                                                                                                                                                                                                                                                                                         | optional (required if `AI_PROVIDER=azure`)                                         |                                                                           |
| AI\_AZURE\_API\_VERSION                                                                        | Azure API version for OpenAI-compatible calls.                                                                                                                                                                                                                                                                                              | optional                                                                           | v1                                                                        |
| AI\_OPENAI\_COMPATIBLE\_BASE\_URL                                                              | Base URL for a Qwen/vLLM OpenAI-compatible `/v1` endpoint, e.g. `http://vllm:8000/v1`.                                                                                                                                                                                                                                                      | optional (required if `AI_PROVIDER=openai-compatible`)                             |                                                                           |
| AI\_OPENAI\_COMPATIBLE\_API\_KEY                                                               | Optional API key for the OpenAI-compatible endpoint.                                                                                                                                                                                                                                                                                        | optional                                                                           |                                                                           |
| AI\_OPENAI\_COMPATIBLE\_PROVIDER\_NAME                                                         | Provider name passed to the OpenAI-compatible adapter. Use `vllm` for the supported Qwen/vLLM self-hosted path.                                                                                                                                                                                                                             | optional                                                                           | openai-compatible                                                         |
| AI\_OPENAI\_COMPATIBLE\_SUPPORTS\_STRUCTURED\_OUTPUTS                                          | Set to `1` when the Qwen/vLLM endpoint supports structured outputs.                                                                                                                                                                                                                                                                         | optional                                                                           | 0                                                                         |
| AI\_OPENAI\_COMPATIBLE\_HEADERS\_JSON                                                          | Optional JSON object of string-valued headers to send with OpenAI-compatible requests.                                                                                                                                                                                                                                                      | optional                                                                           |                                                                           |
| AI\_OPENAI\_COMPATIBLE\_QUERY\_PARAMS\_JSON                                                    | Optional JSON object of string-valued query parameters to send with OpenAI-compatible requests.                                                                                                                                                                                                                                             | optional                                                                           |                                                                           |
| STRIPE\_SECRET\_KEY                                                                            | Secret key for Stripe integration.                                                                                                                                                                                                                                                                                                          | optional                                                                           |                                                                           |
| STRIPE\_WEBHOOK\_SECRET                                                                        | Webhook secret for Stripe integration.                                                                                                                                                                                                                                                                                                      | optional                                                                           |                                                                           |
| DEFAULT\_BRAND\_COLOR                                                                          | Default brand color for your app (Can be overwritten from the UI as well).                                                                                                                                                                                                                                                                  | optional                                                                           | #64748b                                                                   |
| UNSPLASH\_ACCESS\_KEY                                                                          | Unsplash access key used to search Unsplash for survey background images. Without it, the image tab is hidden in the survey editor's background picker and in the Look & Feel settings.                                                                                                                                                     | optional (required for Unsplash background images)                                 |                                                                           |
| AUTH\_SSO\_DEFAULT\_ORGANIZATION\_ID                                                           | Requires an [Enterprise Edition](/docs/self-hosting/advanced/license) licence with SSO. Automatically assigns new SSO users to this organization, without requiring an invitation. Must be a valid CUID; the organization is created with this ID on the first sign-up if it does not exist yet. Renamed from `DEFAULT_ORGANIZATION_ID` in v6.   | optional (Enterprise Edition, SSO)                                                 |                                                                           |
| AUTH\_SSO\_DEFAULT\_ORGANIZATION\_ROLE                                                         | Role given to users auto-assigned by `AUTH_SSO_DEFAULT_ORGANIZATION_ID`. The sign-up that creates the organization is always `owner`. One of `owner`, `manager`, `member`, `billing`. Renamed from `DEFAULT_ORGANIZATION_ROLE` in v6.                                                                                                       | optional (Enterprise Edition, SSO)                                                 | manager                                                                   |
| OIDC\_DISPLAY\_NAME                                                                            | Display name for Custom OpenID Connect Provider                                                                                                                                                                                                                                                                                             | optional                                                                           |                                                                           |
| OIDC\_CLIENT\_ID                                                                               | Client ID for Custom OpenID Connect Provider                                                                                                                                                                                                                                                                                                | optional (required if OIDC auth is enabled)                                        |                                                                           |
| OIDC\_CLIENT\_SECRET                                                                           | Secret for Custom OpenID Connect Provider                                                                                                                                                                                                                                                                                                   | optional (required if OIDC auth is enabled)                                        |                                                                           |
| OIDC\_ISSUER                                                                                   | Issuer URL for Custom OpenID Connect Provider (should have .well-known configured at this)                                                                                                                                                                                                                                                  | optional (required if OIDC auth is enabled)                                        |                                                                           |
| OIDC\_SIGNING\_ALGORITHM                                                                       | Signing Algorithm for Custom OpenID Connect Provider                                                                                                                                                                                                                                                                                        | optional                                                                           | RS256                                                                     |
| OTEL\_EXPORTER\_OTLP\_ENDPOINT                                                                 | Base OTLP HTTP endpoint for traces and metrics export (e.g. [http://collector:4318](http://collector:4318)).                                                                                                                                                                                                                                | optional                                                                           |                                                                           |
| OTEL\_EXPORTER\_OTLP\_PROTOCOL                                                                 | OTLP protocol to use for export.                                                                                                                                                                                                                                                                                                            | optional                                                                           | http/protobuf                                                             |
| OTEL\_SERVICE\_NAME                                                                            | Service name reported in OpenTelemetry resource attributes.                                                                                                                                                                                                                                                                                 | optional                                                                           | formbricks                                                                |
| OTEL\_RESOURCE\_ATTRIBUTES                                                                     | Comma-separated resource attributes in OTel format (`key=value,key2=value2`).                                                                                                                                                                                                                                                               | optional                                                                           |                                                                           |
| OTEL\_TRACES\_SAMPLER                                                                          | Trace sampler strategy (`always_on`, `always_off`, `traceidratio`, `parentbased_traceidratio`).                                                                                                                                                                                                                                             | optional                                                                           | always\_on                                                                |
| OTEL\_TRACES\_SAMPLER\_ARG                                                                     | Sampling argument used by ratio-based samplers (`0` to `1`).                                                                                                                                                                                                                                                                                | optional                                                                           |                                                                           |
| PROMETHEUS\_ENABLED                                                                            | Enables Prometheus metrics if set to 1.                                                                                                                                                                                                                                                                                                     | optional                                                                           |                                                                           |
| PROMETHEUS\_EXPORTER\_PORT                                                                     | Port for Prometheus metrics.                                                                                                                                                                                                                                                                                                                | optional                                                                           | 9090                                                                      |
| AUTH\_SSO\_DEFAULT\_TEAM\_ID                                                                   | ID of the team that new SSO users are automatically added to. The owning organization is derived from this team. Must be set together with `AUTH_SKIP_INVITE_FOR_SSO=1` for auto-provisioning to work.                                                                                                                                      | optional                                                                           |                                                                           |
| AUTH\_SKIP\_INVITE\_FOR\_SSO                                                                   | Set to `1` to allow SSO users to create an account without a manual invite. Keep unset (or `0`) for stricter access control where only invited users can join.                                                                                                                                                                              | optional                                                                           | 0                                                                         |
| HTTP\_PROXY                                                                                    | HTTP proxy URL used for outbound requests (e.g., license checks). When both are set, `HTTPS_PROXY` takes precedence.                                                                                                                                                                                                                        | optional                                                                           |                                                                           |
| HTTPS\_PROXY                                                                                   | HTTPS proxy URL used for outbound requests. Takes precedence over `HTTP_PROXY`.                                                                                                                                                                                                                                                             | optional                                                                           |                                                                           |
| SENTRY\_DSN                                                                                    | Set this to track errors and monitor performance in Sentry.                                                                                                                                                                                                                                                                                 | optional                                                                           |                                                                           |
| SENTRY\_ENVIRONMENT                                                                            | Set this to identify the environment in Sentry                                                                                                                                                                                                                                                                                              | optional                                                                           |                                                                           |
| SENTRY\_AUTH\_TOKEN                                                                            | Set this if you want to make errors more readable in Sentry.                                                                                                                                                                                                                                                                                | optional                                                                           |                                                                           |
| SESSION\_MAX\_AGE                                                                              | Configure the maximum age for the session in seconds.                                                                                                                                                                                                                                                                                       | optional                                                                           | 86400 (24 hours)                                                          |
| USER\_MANAGEMENT\_MINIMUM\_ROLE                                                                | Set this to control which roles can access user management features. Accepted values: "owner", "manager", "disabled"                                                                                                                                                                                                                        | optional                                                                           | manager                                                                   |
| REDIS\_URL                                                                                     | Redis URL for caching, rate limiting, audit logging, and the shared BullMQ background-job queue. All web and worker replicas must share this Redis instance. Application will not start without this.                                                                                                                                       | required                                                                           | redis\://localhost:6379                                                   |
| BULLMQ\_WORKER\_ENABLED                                                                        | Set to `1` to start BullMQ workers inside each Formbricks web process. Set to `0` only in a custom deployment that already runs an external consumer with the complete Formbricks application job handlers.                                                                                                                                 | optional                                                                           | 1 outside test environments                                               |
| BULLMQ\_EXTERNAL\_WORKER\_ENABLED                                                              | Custom integrations only: set to `1` on web/API processes that only enqueue jobs while an external consumer with the complete Formbricks application job handlers processes them. This flag only keeps queueing enabled; it does not provide or start a worker.                                                                             | optional                                                                           | 0                                                                         |
| BULLMQ\_WORKER\_COUNT                                                                          | Number of BullMQ worker instances to start in each Formbricks web process. Must be a positive integer.                                                                                                                                                                                                                                      | optional                                                                           | 1                                                                         |
| BULLMQ\_WORKER\_CONCURRENCY                                                                    | Number of jobs each in-process BullMQ worker can process concurrently. Must be a positive integer.                                                                                                                                                                                                                                          | optional                                                                           | 1                                                                         |
| AUDIT\_LOG\_ENABLED                                                                            | Set this to 1 to enable audit logging. Requires Redis to be configured with the REDIS\_URL env variable.                                                                                                                                                                                                                                    | optional                                                                           | 0                                                                         |
| AUDIT\_LOG\_GET\_USER\_IP                                                                      | Set to 1 to include user IP addresses in audit logs from request headers                                                                                                                                                                                                                                                                    | optional                                                                           | 0                                                                         |
| See [Job Runner](/docs/self-hosting/configuration/job-runner) for BullMQ architecture, scaling, and |                                                                                                                                                                                                                                                                                                                                             |                                                                                    |                                                                           |
| troubleshooting guidance.                                                                      |                                                                                                                                                                                                                                                                                                                                             |                                                                                    |                                                                           |

#### 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:

```text theme={null}
{WEBAPP_URL}/api/mcp
{WEBAPP_URL}/.well-known/oauth-protected-resource/api/mcp
{WEBAPP_URL}/.well-known/oauth-authorization-server/api/auth
```

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:

| Variable           | Description                                                                                                                                       | Required | Default                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| HUB\_API\_KEY      | API key used by the Formbricks Hub API. Generate a strong secret and use the same value wherever your deployment supplies Hub auth configuration. | required | (e.g. `openssl rand -hex 32`)                                           |
| HUB\_API\_URL      | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere.            | required | `http://hub:8080` (bundled Docker), `http://localhost:8080` (local dev) |
| HUB\_DATABASE\_URL | PostgreSQL connection URL for Hub. Omit to use the same database as Formbricks.                                                                   | optional | Same as Formbricks `DATABASE_URL` (shared database)                     |

#### 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.

| Variable             | Description                                                                                                       | Required when enabled | Default                                             |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------- |
| AUTHZED\_ENABLED     | Enables the required AuthZed authorization engine.                                                                | required              | `true` in bundled Docker, Helm, and dev             |
| AUTHZED\_ENDPOINT    | AuthZed gRPC endpoint as `host:port`. The default Helm-managed service is `formbricks-spicedb:50051`.             | required              | `spicedb:50051` in Docker; `localhost:50051` in dev |
| AUTHZED\_TOKEN       | Preshared API token. Always load this from a secret.                                                              | required              |                                                     |
| AUTHZED\_SYSTEM\_KEY | Stable namespace for Formbricks authorization objects and relationships.                                          | required              | `formbricks`                                        |
| AUTHZED\_INSECURE    | Allows plaintext gRPC for an in-cluster service. Keep disabled for endpoints outside the trusted cluster network. | optional              | `true` in Helm and bundled Docker/dev               |
| AUTHZED\_CONSISTENCY | Consistency policy used by authorization decisions.                                                               | optional              | `fully_consistent` in released Docker and Helm      |

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:

```bash theme={null}
docker compose --profile authzed-ops run --rm authzed-ops health
docker compose --profile authzed-ops run --rm authzed-ops upgrade check
```

For Helm, run `formbricks-authzed health` inside a Formbricks application pod. Repository development can keep
using `pnpm authzed:health`. See [AuthZed Operations](/docs/self-hosting/advanced/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.

| Variable              | Description                                                                                                                                           | Required | Default                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------- |
| CUBEJS\_API\_URL      | Base URL the Formbricks app uses to call Cube. Local dev (app on host): `http://localhost:4000`. Docker/container: `http://cube:4000` (service name). | required |                                 |
| CUBEJS\_API\_SECRET   | Shared secret Formbricks uses to sign Cube API JWTs. Generate with `openssl rand -hex 32`.                                                            | required |                                 |
| CUBEJS\_JWT\_ISSUER   | JWT issuer expected by Cube and used by Formbricks when signing per-request Cube tokens.                                                              | optional | `formbricks-web`                |
| CUBEJS\_JWT\_AUDIENCE | JWT audience expected by Cube and used by Formbricks when signing per-request Cube tokens.                                                            | optional | `formbricks-cube`               |
| CUBEJS\_DB\_HOST      | Database host for the Cube service. Only needed when you run Cube yourself and override defaults.                                                     | optional | Depends on your Cube deployment |
| CUBEJS\_DB\_PORT      | Database port for the Cube service. Only needed when you run Cube yourself and override defaults.                                                     | optional | Depends on your Cube deployment |
| CUBEJS\_DB\_NAME      | Database name for the Cube service. Only needed when you run Cube yourself and override defaults.                                                     | optional | Depends on your Cube deployment |
| CUBEJS\_DB\_USER      | Database user for the Cube service. Only needed when you run Cube yourself and override defaults.                                                     | optional | Depends on your Cube deployment |
| CUBEJS\_DB\_PASS      | Database password for the Cube service. Only needed when you run Cube yourself and override defaults.                                                 | optional | Depends on your Cube deployment |

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.
