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

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

Using Managed PostgreSQL And Redis

Using External Secrets

3. v5-Specific Deployment Notes

Hub Is Mandatory

Envoy Bundle Modes

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

​Using Managed PostgreSQL And Redis

​Using External Secrets

​3. v5-Specific Deployment Notes

​Hub Is Mandatory

​Envoy Bundle Modes

​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

Using Managed PostgreSQL And Redis

Using External Secrets

3. v5-Specific Deployment Notes

Hub Is Mandatory

Envoy Bundle Modes

Cube

Optional Bundled Qwen/vLLM For AI

Optional AI Taxonomy Beta

4. Upgrade The Deployment

5. Key Values

6. Uninstalling The Deployment