Skip to main content
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

1

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

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
  • PostgreSQL
  • Redis
  • generated Kubernetes Secrets

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

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

​
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: 
envoyRedis:
  enabled: true
This keeps Envoy rate-limiting state separate from the application’s own Redis traffic.

​
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

FieldDescription
formbricks.webappUrlPublic base URL for the Formbricks app
deployment.image.tagFormbricks image tag override
hub.enabledMust stay true in Formbricks v5
hub.image.tagHub image tag override
envoy.enabledEnables chart-managed Envoy Gateway resources
envoy.controller.enabledInstalls the bundled Envoy controller when true
envoyRedis.enabledDeploys a dedicated Redis backend for Envoy rate limiting
llm.enabledDeploys the optional bundled Qwen/vLLM runtime
llm.autoConfigureAppInjects Formbricks OpenAI-compatible env vars for bundled Qwen
taxonomy.enabledDeploys the optional standalone AI taxonomy service
postgresql.externalDatabaseUrlUses an external PostgreSQL service instead of in-cluster
redis.externalRedisUrlUses 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