Kubernetes Deployment

Deploy Formbricks on Kubernetes using the current OCI Helm chart published from the charts/formbricks directory in the Formbricks repository.

Formbricks v5 self-hosting expects Hub to be part of the runtime. The chart handles that by default. Use the migration guide before upgrading an existing 4.x deployment.

Prerequisites

Ensure you have the following before proceeding:

a running Kubernetes cluster
Helm 3 installed locally
a public hostname for formbricks.webappUrl
a plan for PostgreSQL and Redis/Valkey, either in-cluster or managed externally
an edge rate-limiting plan for the v5-covered routes: the chart’s Envoy bundle or an equivalent external edge solution

1. Install The Chart

Create A Minimal values.yaml

formbricks:
  webappUrl: https://surveys.example.com

Add any additional overrides you need for ingress, external services, secrets, or Enterprise license features.

Install Formbricks

helm install formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \
  -n formbricks \
  --create-namespace \
  -f values.yaml

By default, the chart deploys:

the Formbricks application
Formbricks Hub
Cube
PostgreSQL
Redis
generated Kubernetes Secrets

The default values are a starting point, not a production edge or high-availability configuration. Both ingress.enabled and envoy.enabled default to false, so the chart does not expose the application or add the v5 edge rate limits unless you configure them. The defaults also combine autoscaling.minReplicas: 1 with pdb.minAvailable: 1; that PodDisruptionBudget can block a node drain because Kubernetes cannot voluntarily evict the only app pod.

2. Configure Secrets And External Services

Using Generated Secrets

The default chart path keeps secret.enabled: true, which lets the chart generate the required application secrets for you.

Adding An Enterprise License

There is no separate enterprise.enabled switch. Enterprise features are unlocked by a valid ENTERPRISE_LICENSE_KEY. For a quick-start deployment that uses the chart-generated app Secret, set:

enterprise:
  licenseKey: your-enterprise-license-key

For production, keep the license out of a values file and provide ENTERPRISE_LICENSE_KEY through your existing Secret or ExternalSecret instead. The enterprise.licenseKey chart value only writes to the generated app Secret when secret.enabled: true.

Using Managed PostgreSQL And Redis

For production workloads, many teams prefer managed services:

postgresql:
  enabled: false
  externalDatabaseUrl: "postgresql://user:password@your-postgres-host:5432/formbricks"

redis:
  enabled: false
  externalRedisUrl: "redis://your-redis-host:6379"

Using External Secrets

If your cluster already uses an external secret manager, enable externalSecret and point it at your existing SecretStore. Ensure the resulting app secret exposes the values your deployment needs, including DATABASE_URL, REDIS_URL, and HUB_API_KEY.

AuthZed / SpiceDB

Formbricks v6 uses AuthZed as its authorization engine. Fresh chart installations enable a private, two-replica SpiceDB cluster and fully_consistent decisions by default. If the cluster already has a compatible SpiceDB operator, keep the authorization runtime enabled but disable this release’s operator installation:

authzed:
  operator:
    install: false

The default authzed.operator.install: true installs the pinned operator, creates the cluster, and bootstraps a dedicated spicedb database and login. Install only one operator in a Kubernetes cluster. For managed PostgreSQL, create a separate SpiceDB database and login first. Store its connection URI and a strong API token in a Kubernetes Secret using the keys datastore_uri and preshared_key, then configure:

authzed:
  enabled: true
  auth:
    existingSecret: formbricks-authzed
  datastore:
    existingSecret: formbricks-authzed

Use authzed.mode: external, authzed.operator.install: false, authzed.endpoint: <host>:<port>, and authzed.insecure: false when connecting to an externally managed AuthZed endpoint. The external endpoint must serve TLS because the preshared token is sent on every authenticated request. The application endpoint remains internal and uses plaintext gRPC by default when the chart owns SpiceDB. Helm prints release-specific commands that execute the release-matched operator CLI inside a Formbricks pod. Start with:

kubectl exec -n <namespace> deployment/<release-name> -- formbricks-authzed health
kubectl exec -n <namespace> deployment/<release-name> -- formbricks-authzed schema check
kubectl exec -n <namespace> deployment/<release-name> -- formbricks-authzed upgrade check

A fresh install runs an idempotent initialization Job, but application startup and probes remain independent from it. Upgrades never run relationship preparation automatically. Before the first v6 upgrade, run formbricks-authzed upgrade prepare, require upgrade check to exit 0, and then set authzed.migrationAcknowledged: true. The chart refuses an unacknowledged upgrade, disabled AuthZed, or weaker consistency. Follow AuthZed Operations and do not expose SpiceDB through an Ingress.

3. v5-Specific Deployment Notes

Hub Is Mandatory

Formbricks v5 does not support hub.enabled=false. Keep the default hub.enabled=true behavior in place. Use hub.image.tag, hub.resources, and hub.existingSecret only when you need to pin or customize the Hub deployment details.

Envoy Bundle Modes

The chart supports three edge patterns for the v5-covered routes:

Bundled Envoy controller: set envoy.enabled=true and envoy.controller.enabled=true
Existing cluster Envoy controller: set envoy.enabled=true and envoy.controller.enabled=false
Equivalent external edge protection: keep using your platform’s own ingress or gateway layer if it already provides equivalent rate-limiting coverage

If you use the chart-managed Envoy rate-limiting path, enable a dedicated backend with:

envoy:
  enabled: true
  controller:
    enabled: true

envoyRedis:
  enabled: true

This keeps Envoy rate-limiting state separate from the application’s own Redis traffic. The example installs the bundled controller. If your cluster already provides a compatible Envoy Gateway controller, set envoy.controller.enabled: false. In either mode, configure envoy.formbricks.ingress or your platform ingress/load balancer so public traffic reaches the Envoy-managed routes. If you use an equivalent external edge solution instead, verify that it covers every route in the rate-limiting guide before exposing Formbricks.

Production Replicas And Disruption Budgets

For a production deployment that should remain available during a voluntary disruption, run at least two app replicas:

autoscaling:
  enabled: true
  minReplicas: 2

pdb:
  enabled: true
  minAvailable: 1

If you intentionally run a single app replica, either disable the PDB or use maxUnavailable: 1 instead of minAvailable and accept downtime during the eviction. Never set both fields; set the unused field to null in your values file. Two autoscaling defaults are easy to miss:

maxReplicas: 10 can exceed what the node pool can hold. Each app pod requests 1 vCPU, so the ceiling needs about 10 allocatable vCPU for the app alone, on top of the platform reserve and the Hub, Cube and SpiceDB pods. A smaller pool leaves the extra replicas Pending — an HPA does not lower its own ceiling.
The HPA scales on CPU and memory utilization only. Queue depth is not one of its metrics, so a job backlog can grow while both targets sit under their thresholds and no replica is added. Backlog-driven scaling needs a queue-depth metric published to the metrics API and added to the HPA yourself.

Cube

Cube is part of the baseline Formbricks v5 stack and is bundled with the chart by default (cube.enabled: true). To run an external Cube cluster instead:

set cube.enabled: false to skip the bundled Cube deployment
point the app at your external endpoint via deployment.env.CUBEJS_API_URL
supply CUBEJS_API_SECRET via deployment.env or deployment.envFrom if you disable generated secrets

Optional Bundled Qwen/vLLM For AI

The Helm chart can optionally deploy a Formbricks-provided Qwen runtime through vLLM. This is disabled by default and requires GPU-capable Kubernetes nodes. To deploy Qwen/vLLM and automatically point the Formbricks app at the in-cluster OpenAI-compatible endpoint:

llm:
  enabled: true

With llm.enabled: true, the chart renders the vLLM router and Qwen serving engine, then injects the required AI_PROVIDER=openai-compatible app environment variables unless you override them in deployment.env. If you want to deploy the bundled Qwen runtime without changing the Formbricks app AI configuration:

llm:
  enabled: true
  autoConfigureApp: false

Keep llm.enabled: false when you use Google Vertex, Azure, AWS Bedrock, or an externally managed OpenAI-compatible endpoint. Configure those providers through deployment.env.

Optional AI Taxonomy Beta

The Helm chart can optionally deploy the standalone taxonomy service. This is disabled by default and does not force the bundled Qwen/vLLM runtime. To deploy taxonomy and reuse the bundled Qwen/vLLM runtime:

llm:
  enabled: true

taxonomy:
  enabled: true

With this setup, taxonomy uses the in-cluster vLLM router for cluster labeling and 5-level taxonomy generation. The chart also injects TAXONOMY_SERVICE_URL, TAXONOMY_SERVICE_TOKEN, and HUB_INTERNAL_API_TOKEN into Hub API. To use your own OpenAI-compatible LLM endpoint instead, keep llm.enabled: false and set the taxonomy LLM values:

taxonomy:
  enabled: true
  llm:
    model: qwen3-14b-awq
    baseUrl: http://my-llm-gateway:8000/v1
    existingSecret: taxonomy-llm-secret

The taxonomy-llm-secret secret must contain TAXONOMY_LLM_API_KEY. If your endpoint does not enforce authentication, store a non-empty dummy value. To use Gemini on Vertex AI instead, keep llm.enabled: false, create a secret containing TAXONOMY_GOOGLE_CLOUD_CREDENTIALS_JSON, and configure the Vertex provider:

taxonomy:
  enabled: true
  llm:
    provider: vertex-gemini
    model: gemini-2.5-flash
    vertex:
      project: formbricks-cloud
      location: europe-west3
      existingSecret: taxonomy-vertex-secret

The service account in TAXONOMY_GOOGLE_CLOUD_CREDENTIALS_JSON must be allowed to call Vertex AI for the selected project and location. After startup, run the authenticated preflight check from inside the taxonomy pod:

kubectl exec -n formbricks deploy/formbricks-taxonomy -- \
  python -c 'import os, urllib.request; req = urllib.request.Request("http://127.0.0.1:8000/v1/preflight", headers={"Authorization": "Bearer " + os.environ["TAXONOMY_SERVICE_TOKEN"]}); print(urllib.request.urlopen(req, timeout=10).read().decode())'

The taxonomy service is internal-only by default. Kubernetes probes use public /health; /v1/preflight is for operator validation and requires the internal taxonomy bearer token.

4. Upgrade The Deployment

For normal chart upgrades:

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

For a Formbricks 4.x to 5.0 migration, confirm the following before running the upgrade:

Hub remains enabled
HUB_API_KEY is present
your edge rate-limiting plan is in place
any required AI_* variables are added
CUBEJS_API_SECRET is configured (the generated app secret supplies it by default; provide an external endpoint if you set cube.enabled: false)

5. Key Values

Field	Description
`formbricks.webappUrl`	Public base URL for the Formbricks app
`deployment.image.tag`	Formbricks image tag override
`hub.enabled`	Must stay `true` in Formbricks v5
`hub.image.tag`	Hub image tag override
`envoy.enabled`	Enables chart-managed Envoy Gateway resources
`envoy.controller.enabled`	Installs the bundled Envoy controller when `true`
`envoyRedis.enabled`	Deploys a dedicated Redis backend for Envoy rate limiting
`llm.enabled`	Deploys the optional bundled Qwen/vLLM runtime
`llm.autoConfigureApp`	Injects Formbricks OpenAI-compatible env vars for bundled Qwen
`taxonomy.enabled`	Deploys the optional standalone AI taxonomy service
`postgresql.externalDatabaseUrl`	Uses an external PostgreSQL service instead of in-cluster
`redis.externalRedisUrl`	Uses an external Redis/Valkey service instead of in-cluster

For the complete values surface, refer to the chart README in the repository: charts/formbricks/README.md.

6. Uninstalling The Deployment

To remove the deployment:

helm uninstall formbricks -n formbricks

If you also want to remove in-cluster persistent volumes:

kubectl delete pvc --all -n formbricks

Self Hosting

Setup

Configuration

Advanced

Prerequisites

1. Install The Chart

2. Configure Secrets And External Services

Using Generated Secrets

Adding An Enterprise License

Using Managed PostgreSQL And Redis

Using External Secrets

AuthZed / SpiceDB

3. v5-Specific Deployment Notes

Hub Is Mandatory

Envoy Bundle Modes

Production Replicas And Disruption Budgets

Cube

Optional Bundled Qwen/vLLM For AI

Optional AI Taxonomy Beta

4. Upgrade The Deployment

5. Key Values

6. Uninstalling The Deployment

​Prerequisites

​1. Install The Chart

​2. Configure Secrets And External Services

​Using Generated Secrets

​Adding An Enterprise License

​Using Managed PostgreSQL And Redis

​Using External Secrets

​AuthZed / SpiceDB

​3. v5-Specific Deployment Notes

​Hub Is Mandatory

​Envoy Bundle Modes

​Production Replicas And Disruption Budgets

​Cube

​Optional Bundled Qwen/vLLM For AI

​Optional AI Taxonomy Beta

​4. Upgrade The Deployment

​5. Key Values

​6. Uninstalling The Deployment

Prerequisites

1. Install The Chart

2. Configure Secrets And External Services

Using Generated Secrets

Adding An Enterprise License

Using Managed PostgreSQL And Redis

Using External Secrets

AuthZed / SpiceDB

3. v5-Specific Deployment Notes

Hub Is Mandatory

Envoy Bundle Modes

Production Replicas And Disruption Budgets

Cube

Optional Bundled Qwen/vLLM For AI

Optional AI Taxonomy Beta

4. Upgrade The Deployment

5. Key Values

6. Uninstalling The Deployment