formbricks/docs/self-hosting/setup/kubernetes.mdx

---
title: "Kubernetes Deployment"
description: "Deploy Formbricks on Kubernetes with the current OCI Helm chart."
icon: "circle-nodes"
---

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

<Info>
  Formbricks v5 self-hosting expects Hub to be part of the runtime. The chart handles that by default. Use the
  [migration guide](/self-hosting/advanced/migration#v5) before upgrading an existing 4.x deployment.
</Info>

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

<Steps>
<Step title="Create A Minimal values.yaml">

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

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

<Step title="Install Formbricks">

```sh
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
</Step>
</Steps>

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

```yaml
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:

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

## 4. Upgrade The Deployment

For normal chart upgrades:

```sh
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 (Cube is bundled 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     |
| `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](https://github.com/formbricks/formbricks/tree/main/charts/formbricks).

## 6. Uninstalling The Deployment

To remove the deployment:

```sh
helm uninstall formbricks -n formbricks
```

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

```sh
kubectl delete pvc --all -n formbricks
```