# Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm.md

---
title: Kubernetes (Helm) (self-hosted)
description: Step-by-step guide to run Langfuse on Kubernetes via Helm.
label: "Version: v3"
sidebarTitle: "Kubernetes (Helm)"
---

# 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](/self-hosting#architecture)).
You can optionally point to an existing PostgreSQL, Clickhouse and Redis instance.
See [Readme](https://github.com/langfuse/langfuse-k8s/blob/main/README.md) for more details.

<Callout type="info">
  If you are interested in contributing to our Kubernetes deployment guide or
  Helm chart, please create an issue on the [GitHub
  Discussion](https://github.com/orgs/langfuse/discussions/1902).
</Callout>

<Callout type="info">

Alternatively, you can use one of the following cloud-specific deployment guides:

- [AWS (Terraform)](/self-hosting/deployment/aws)
- [Azure (Terraform)](/self-hosting/deployment/azure)
- [GCP (Terraform)](/self-hosting/deployment/gcp)
- [Railway](/self-hosting/deployment/railway)

</Callout>

## Fetch the Helm chart and customize values

Fetch the `langfuse-k8s` Helm chart.

```bash
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](/self-hosting/configuration) and the [Readme](https://github.com/langfuse/langfuse-k8s/blob/main/README.md).

## Deploy the helm chart

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

```bash
kubectl create namespace langfuse
```

Install the Helm chart into your namespace:

```bash
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](https://github.com/langfuse/langfuse-k8s)

import { useData } from "nextra/hooks";
import { Playground } from "nextra/components";
import { Callout } from "nextra/components";

export const getStaticProps = async () => {
  const res = await fetch(
    "https://raw.githubusercontent.com/langfuse/langfuse-k8s/refs/heads/main/README.md"
  );
  const readmeContent = await res.text();
  return {
    props: {
      ssg: {
        helmReadme: readmeContent,
      },
    },
  };
};

export function HelmReadme() {
  const { helmReadme } = useData();
  // Basic check to prevent errors if fetching failed or content is empty
  if (!helmReadme) {
    return <p>Error loading README content.</p>;
  }
  // Ensure the source prop receives a string
  const readmeString =
    typeof helmReadme === "string" ? helmReadme : JSON.stringify(helmReadme);
  return <Playground source={readmeString} />;
}

<div className="p-6 mt-6 border bg-card rounded-md">
  <HelmReadme />
</div>

## Features

Langfuse supports many configuration options and self-hosted features.
For more details, please refer to the [configuration guide](/self-hosting/configuration).



import {
  Lock,
  Shield,
  Network,
  Users,
  Brush,
  Workflow,
  UserCog,
  Route,
  Mail,
  ServerCog,
  Activity,
  Eye,
  Zap,
} from "lucide-react";

import { Cards } from "nextra/components";

<Cards num={3}>
  <Cards.Card
    icon={<Lock size="24" />}
    title="Authentication & SSO"
    href="/self-hosting/security/authentication-and-sso"
    arrow
  />
  <Cards.Card
    icon={<UserCog size="24" />}
    title="Automated Access Provisioning"
    href="/self-hosting/administration/automated-access-provisioning"
    arrow
  />
  <Cards.Card
    icon={<Zap size="24" />}
    title="Caching"
    href="/self-hosting/configuration/caching"
    arrow
  />
  <Cards.Card
    icon={<Route size="24" />}
    title="Custom Base Path"
    href="/self-hosting/configuration/custom-base-path"
    arrow
  />
  <Cards.Card
    icon={<Shield size="24" />}
    title="Encryption"
    href="/self-hosting/configuration/encryption"
    arrow
  />
  <Cards.Card
    icon={<Workflow size="24" />}
    title="Headless Initialization"
    href="/self-hosting/administration/headless-initialization"
    arrow
  />
  <Cards.Card
    icon={<Network size="24" />}
    title="Networking"
    href="/self-hosting/security/networking"
    arrow
  />
  <Cards.Card
    icon={<Users size="24" />}
    title="Organization Creators (EE)"
    href="/self-hosting/administration/organization-creators"
    arrow
  />
  <Cards.Card
    icon={<ServerCog size="24" />}
    title="Instance Management API (EE)"
    href="/self-hosting/administration/instance-management-api"
    arrow
  />
  <Cards.Card
    icon={<Activity size="24" />}
    title="Health and Readiness Check"
    href="/self-hosting/configuration/health-readiness-endpoints"
    arrow
  />
  <Cards.Card
    icon={<Eye size="24" />}
    title="Observability via OpenTelemetry"
    href="/self-hosting/configuration/observability"
    arrow
  />
  <Cards.Card
    icon={<Mail size="24" />}
    title="Transactional Emails"
    href="/self-hosting/configuration/transactional-emails"
    arrow
  />
  <Cards.Card
    icon={<Brush size="24" />}
    title="UI Customization (EE)"
    href="/self-hosting/administration/ui-customization"
    arrow
  />
</Cards>



## Shutdown

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

```bash
helm uninstall langfuse -n langfuse
kubectl delete namespace langfuse
```

## How to Upgrade

Run the following commands to upgrade the Helm chart to the latest version:

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

For more details on upgrading, please refer to the [upgrade guide](/self-hosting/upgrade).