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

# Kubernetes Deployment

> Deploy Formbricks on Kubernetes with the current OCI Helm chart.

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 theme={null}
    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 theme={null}
    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 theme={null}
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 theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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`.

## 4. Upgrade The Deployment

For normal chart upgrades:

```sh theme={null}
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 |
| `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 theme={null}
helm uninstall formbricks -n formbricks
```

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

```sh theme={null}
kubectl delete pvc --all -n formbricks
```