Kubernetes (Helm)

This guide will walk you through the steps to deploy Langfuse on Kubernetes using the Helm package manager. You will need access to a Kubernetes cluster and Helm installed on your local machine. For the purposes of this guide, we will use a local minikube instance, but each step should extend to a managed Kubernetes service like GKE, EKS, or AKS.

By default, the chart will deploy the Langfuse application containers and data stores (architecture overview). You can optionally point to an existing PostgreSQL, Clickhouse and Redis instance. See Readme for more details.

Prerequisites

• Kubernetes v1.28 or newer, as required by the ClickHouse Kubernetes Operator.
• cert-manager and the ClickHouse operator, installed once per cluster. From chart version v2.0.0 onwards, clickhouse.deploy: true (the default) renders ClickHouseCluster and KeeperCluster resources, and the operator creates cert-manager resources for its webhooks. Both CRD sets must exist before helm install; the chart preflights the ClickHouse CRDs and fails fast if they are missing. The Readme below lists the exact install commands.

Deployments that point every data store at an external service (*.deploy: false) do not need the operator.

Fetch the Helm chart and customize values

Fetch the langfuse-k8s Helm chart.

helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update

For local experimentation, the pre-configured variables in the values.yaml file are usually sufficient.

If you send any kind of sensitive data to the application or intend to keep it up for longer, we recommend that you modify the values.yaml file according to your needs

For a comprehensive overview of all available environment variables and configuration options, please refer to the configuration guide and the Readme.

Deploy the helm chart

Create a new namespace for the Langfuse deployment (optional), e.g.:

kubectl create namespace langfuse

Install the Helm chart into your namespace:

helm install langfuse langfuse/langfuse -n langfuse

Our chart assumes that it's installed as langfuse. If you want to install it with a different name, you will have to adjust the Redis hostname in the values.yaml accordingly.

At this point, Kubernetes will start to deploy the Langfuse application and its dependencies. This can take up to 5 minutes. You can monitor the progress by checking kubectl get pods -n langfuse - we expect all pods to be running eventually. The langfuse-web and langfuse-worker container will restart a couple of times while the databases are being provisioned.

Smoke test UI

The Langfuse UI will be served on a ClusterIP service by default. Use kubectl get services -n langfuse and search for langfuse-web to see the port mapping. Create a port-forward via kubectl port-forward svc/langfuse-web -n langfuse <local-port>:<nodeport> and access the UI via http://localhost:<local-port> in your browser. Go ahead and register, create a new organization, project, and explore Langfuse.

Readme

Source: langfuse/langfuse-k8s

Features

Langfuse supports many configuration options and self-hosted features. For more details, please refer to the configuration guide.

Shutdown

You can delete the Helm release and the namespace to clean up the resources:

helm uninstall langfuse -n langfuse
kubectl delete namespace langfuse

How to Upgrade

Run the following commands to upgrade the Helm chart within a chart major version:

helm repo update
helm upgrade langfuse langfuse/langfuse -n langfuse

For more details on upgrading Langfuse itself, please refer to the upgrade guide.

Upgrade the chart from v1 to v2

If you run the bundled ClickHouse (clickhouse.deploy: true), complete the chart v1 to v2 upgrade before you upgrade Langfuse to v4. The v1 chart cannot bring its bundled ClickHouse to the version that Langfuse v4 requires; the v2 chart can. Deployments that connect to an external ClickHouse are not affected and can upgrade Langfuse to v4 independently of the chart.

Chart v2.0.0 ships Langfuse v4 as its default appVersion. To keep the chart migration and the Langfuse v4 upgrade as two separate steps, pin langfuse.image.tag to your current Langfuse v3 image while you move to the v2 chart, then follow the v3 to v4 upgrade guide. To stay on the v1 chart for now, pass a 1.x chart version explicitly via helm upgrade --version.

If you experience any issues when self-hosting Langfuse, please:

1. Check out Troubleshooting & FAQ page.
2. Use Ask AI to get instant answers to your questions.
3. Ask the maintainers on GitHub Discussions.
4. Create a bug report or feature request on GitHub.