Self-Hosting Langfuse in 2026: Docker Compose vs. Kubernetes Helm Chart v2.0.0

Langfuse's open-source LLM observability platform can be self-hosted with the same codebase that powers Langfuse Cloud, which turns the adoption question into an infrastructure decision rather than a feature trade-off. The project documents two primary paths: a Docker Compose stack intended for testing and low-scale deployments, and a Kubernetes deployment driven by the official Helm chart. Helm chart v2.0.0 is a major release that replaces every bundled Bitnami sub-chart with an OSS-licensed alternative and ships Langfuse v4 as its default app version, changing both what a fresh install looks like and how existing v1 releases must migrate. The decision also extends to the backing data stores, most notably PostgreSQL, where managed services and self-managed Kubernetes deployments carry different operational obligations. This guide compares the two deployment paths, walks through the v2.0.0 chart's changes and migration requirements, and lays out criteria for choosing between managed and self-managed Postgres. It is aimed at platform and DevOps engineers planning or operating a self-hosted Langfuse instance at team or production scale.

What Self-Hosting Actually Runs: The Shared Stack Behind Both Paths

What Self‑Hosting Actually Runs: The Shared Stack Behind Both Paths

Langfuse’s self‑hosted offering is identical to the code that powers Langfuse Cloud; the only difference is where the components are run. All required services are open‑source, so the platform can be deployed in a private VPC, on‑premises, or in air‑gapped networks where internet access is optional ⁶.

Application containers

Container	Role
Langfuse Web	Serves the Console UI and public API
Langfuse Worker	Executes background jobs (event processing, email sending, etc.)

Separating the web‑facing service from the worker enables independent scaling of request handling versus asynchronous workloads ⁵.

Storage layer

Langfuse relies on four independent stores, each of which can be run with OSS images or replaced by managed equivalents:

Store	Purpose	Typical OSS implementation
PostgreSQL	Transactional data (users, projects, API keys)	Bitnami, Supabase, or community‑maintained images
ClickHouse	OLAP store for traces, observations, scores	Official ClickHouse image
Redis/Valkey	Queueing and caching of short‑lived data	Redis or its Valkey fork
S3‑compatible blob store	Large event payloads, multimodal inputs, export archives	MinIO or any S3‑compatible service

An optional external LLM API or gateway is required only for features that invoke a model directly from the platform ¹.

Deployment pathways

Path	Typical use‑case	Who maintains the tooling
Docker Compose	Low‑scale testing, personal projects, demos	Langfuse core team (official repo)
Kubernetes Helm chart (v2.0.0)	Production‑grade workloads, autoscaling, high availability	Helm chart community (Langfuse team)
Terraform (AWS, Azure, GCP)	Cloud‑native infra‑as‑code for managed clusters	Cloud provider community & Langfuse docs
Community options (Render, Railway v3)	Teams preferring hosted Kubernetes‑like platforms	Community maintainers

The official documentation notes that the tooling for each path is maintained and tested by different parties, so compatibility and upgrade cadence can vary ⁷.

Licensing

The core platform is released under the MIT license, providing all essential observability features without cost. Certain premium extensions (e.g., advanced analytics dashboards) require a separate license key to unlock ⁶.

Together, these components form a single logical stack that underlies both the Docker‑Compose and Helm‑based deployments, allowing engineers to choose the operational model that best fits their scale and governance requirements.

The Docker Compose Path: Setup, Hardening, and Hard Limits

The Docker Compose Path: Setup, Hardening, and Hard Limits

Prerequisites

• git (to clone the repository)
• Docker Engine and Docker Compose. On macOS or Windows use Docker Desktop; on Ubuntu install Docker from the official apt repository 【2†L1-L5】.

Step‑by‑step deployment

1. Clone the source

   git clone https://github.com/langfuse/langfuse.git
   cd langfuse
   

2. Secure the secrets – open docker-compose.yml and replace every value tagged with # CHANGEME (e.g., POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD, APP_SECRET). Use long, random strings; the documentation explicitly calls for strong passwords 【0†L1-L4】.
3. Start the stack

   docker compose up -d
   

4. Wait for readiness – after roughly 2–3 minutes the langfuse-web-1 container logs “Ready”, and the UI becomes reachable at http://localhost:3000 【1†L1-L5】.

VM hardening (Ubuntu example)

Action	Reason	How‑to
Restrict inbound traffic	Only the web UI (port 3000) and MinIO (port 9090) should be exposed	Configure a security group or ufw rule to allow 3000/tcp and 9090/tcp and deny everything else 【0†L1-L4】
Use strong passwords	Secrets marked # CHANGEME are the sole line of defense against unauthorized access	Generate >20‑character random strings for each secret before starting the stack 【0†L1-L4】
Keep the host OS patched	Reduces attack surface for Docker daemon exploits	Regular apt update && apt upgrade on Ubuntu

Explicit limits of the Compose setup

• No horizontal scaling – Docker Compose does not provide built‑in load‑balancing or multi‑node orchestration 【2†L1-L4】.
• No high‑availability – a single‑instance failure brings the whole service down 【2†L1-L4】.
• No built‑in backup – the stack lacks automated dump or snapshot tools; operators must craft their own backup/restore pipeline 【2†L1-L4】.

When to use Docker Compose

• Development, CI testing, or demos where a single instance suffices.
• Small teams with modest ingestion rates that can tolerate manual backup and no HA.
• Scenarios that benefit from the bundled PostgreSQL container, eliminating the need for an external DB 【1†L1-L5】.

If the project outgrows these constraints—requiring high availability, horizontal scaling, or managed backup/monitoring—plan a migration to the Kubernetes Helm chart. The Compose path is intentionally minimal but fully extensible via the Langfuse configuration guide for authentication, integrations, and advanced settings 【3†L1-L5】.

Inside Helm Chart v2.0.0: Six Changes That Reshape the Bundle

Inside Helm Chart v2.0.0: Six Changes That Reshape the Bundle

Langfuse v2.0.0 is a major Helm‑chart release. The chart no longer relies on Bitnami‑maintained sub‑charts; every bundled service is provided by an OSS‑licensed alternative. The six concrete swaps are:

#	Change	What it replaces	Operational impact
1	OSS‑licensed sub‑charts	All Bitnami sub‑charts	Guarantees a fully FOSS stack; version numbers must be pinned because the new charts use different StatefulSet names and PVC schemas.
2	ClickHouse Operator	Bitnami ClickHouse sub‑chart	Deploys the official ClickHouse Kubernetes Operator (requires CRDs for ClickHouseCluster and KeeperCluster). The operator brings built‑in TLS and automated topology, but the chart now pre‑flights the CRDs and aborts if they are missing.
3	PostgreSQL via groundhog2k/postgres	Bitnami PostgreSQL	Switches to the community groundhog2k/postgres chart, which bundles a different postgresql image and storage class. PVC names change, so a direct helm upgrade from v1 is blocked.
4	Valkey (valkey‑io/valkey)	Bitnami Redis	Replaces Redis with the BSD‑licensed Valkey fork. This avoids the licensing drift that started in March 2024 when Redis moved to a dual RSALv2/SSPL model, a change the OSI does not classify as open source �¹.
5	SeaweedFS object store	No bundled object store (previously external or MinIO)	Introduces SeaweedFS as the default object storage layer, simplifying volume management with a single StatefulSet.
6	Langfuse v4 as default appVersion	Langfuse v3.x	Fresh installations now run v4 out of the box; older v1 releases must upgrade the application after the data‑store migration.

Why the swaps matter

• Licensing safety: By using Valkey, the chart insulates operators from Redis’s non‑FOSS licensing ⁲.
• Operator‑driven lifecycle: The ClickHouse Operator provides automated scaling, rolling updates, and self‑healing, which were unavailable in the static Bitnami chart.
• Consistent OSS pedigree: All components are released under permissive licences (BSD, Apache 2.0, MIT), aligning with Langfuse’s claim that the self‑hosted stack has no non‑FOSS dependency Langfuse Helm docs.

Upgrade consequence

Because the new chart introduces different StatefulSet identities and PVC layouts, a plain helm upgrade from a v1 release that deployed any bundled store is rejected. The chart reports a validation error and aborts the upgrade, forcing operators to perform a data migration (e.g., spin up a parallel v2 release, copy data, then switch traffic). This restriction is documented in the official Helm guide Langfuse Helm docs.

Practical tip

Treat the chart’s defaults, sub‑chart versions, and appVersion as version‑sensitive values. Pin the chart version (e.g., langfuse-k8s-2.0.0) and verify the exact sub‑chart releases in the chart’s Chart.yaml. Do not assume that a future patch will retain the same PVC naming or resource labels; mismatches can cause silent deployment failures.

Prerequisites and First Install on the v2.0.0 Chart

Prerequisites

• Kubernetes version ≥ 1.28 – required by the ClickHouse Kubernetes Operator.
• Helm CLI installed locally (compatible with Helm 3).
• Cluster access – any Kubernetes cluster is acceptable (e.g., minikube, GKE, EKS, AKS).
• cert‑manager and the ClickHouse operator must be installed once per cluster before the first Langfuse install.
  • From Helm chart v2.0.0 the default clickhouse.deploy: true renders ClickHouseCluster and KeeperCluster resources; the operator creates the cert‑manager objects needed for its webhooks.
  • The chart performs a pre‑flight check for the ClickHouse CRDs and aborts if they are missing — a clean install therefore requires both CRD sets to be present 【1】.
• External data stores (PostgreSQL, ClickHouse, Valkey) can be used by setting *.deploy: false. In that case the operator and cert‑manager are not required.

Installation Flow

1. (Optional) Create a namespace for isolation, e.g.:

   kubectl create namespace langfuse
   

2. Add the official repo and install the chart (the chart assumes the release name langfuse):

   helm repo add langfuse https://helm.langfuse.com
   helm repo update
   helm install langfuse langfuse/langfuse-k8s -n langfuse
   

   • If a different release name is chosen, edit values.yaml and adjust the Redis hostname accordingly 【4】.
3. Verify the pre‑flight checks: Helm will immediately error if the ClickHouse CRDs or cert‑manager are absent, preventing a half‑configured deployment.

First‑Deploy Expectations

• Provisioning time: The full stack (ClickHouse, PostgreSQL, Valkey, SeaweedFS, and Langfuse pods) typically finishes within ≈ 5 minutes.
• Pod restarts: langfuse-web and langfuse-worker containers will restart a few times while their backing databases initialise. This is intentional; monitor progress with:

  kubectl get pods -n langfuse -w
  

  Rather than treating the restarts as failures, consider them guardrails that ensure the services only become ready after the stores are healthy.
• UI access: By default the UI is exposed through a ClusterIP service. For quick testing, port‑forward the service:

  kubectl port-forward svc/langfuse-web 3000:80 -n langfuse
  

  Then open http://localhost:3000. In production, replace the port‑forward with an Ingress resource and TLS configuration.

Following this checklist and flow yields a deterministic first installation of the Langfuse v2.0.0 Helm chart, with clear expectations around the short “restart‑and‑wait” phase and the subsequent steps needed to expose the UI securely.

Migrating from Chart v1 to v2: Two Paths and a Critical Ordering Rule

Migration paths defined by the official guide

The Helm chart upgrade documentation distinguishes two mutually exclusive scenarios:

1. External data stores – All *.deploy flags are set to false for PostgreSQL, ClickHouse, Redis/Valkey, and any object store. In this case the v1 release can be upgraded in place with a simple helm upgrade. No PVC or StatefulSet identity changes are involved, so the upgrade proceeds without data‑migration steps.

2. Bundled data stores – When any store is deployed by the chart (*.deploy: true), the v1 release cannot be upgraded directly. The guide instructs you to install a sibling v2 release alongside the existing deployment, copy the persisted data (PostgreSQL dump, ClickHouse DETACH/ATTACH or similar), and then switch traffic to the new release. The requirement stems from the new chart’s PVC layout and StatefulSet names, which are incompatible with the old objects.

“Your deployment must run at least Langfuse v3.224.1 before starting the chart migration.” – the guide marks this as a version‑sensitive prerequisite【1†L1-L4】.

Critical ordering rule for ClickHouse

If the deployment uses the bundled ClickHouse (clickhouse.deploy: true), the chart migration must be completed before upgrading the application to Langfuse v4. The v1 chart cannot bring its bundled ClickHouse to the minimum version required by Langfuse v4, while the v2 chart provisions a ClickHouse version that satisfies the new requirements.

• Langfuse v3 works with ClickHouse ≥ 24.3.
• Langfuse v4 requires ClickHouse ≥ 25.12 (26.4 is recommended).

These version constraints are documented in the ClickHouse deployment guide【3†L1-L3】. Deployments that already point to an external ClickHouse are exempt; they may upgrade the Langfuse image to v4 independently of the Helm chart migration.

Practical advice for a safe transition

• Pin appVersion in the v2 Chart.yaml to the current v3 release (e.g., 3.224.1). This keeps the chart‑upgrade and the subsequent Langfuse v4 upgrade as separate, auditable change events.
• Validate the data‑copy procedure on a staging cluster before executing it in production. Replicate the PVC sizing, StatefulSet names, and ClickHouse DETACH/ATTACH steps to catch any hidden incompatibilities.
• After traffic is switched, confirm that the new release reads and writes to the copied stores before decommissioning the old v1 resources.

Following these steps ensures a deterministic migration path, respects the ClickHouse version ordering, and minimizes downtime for production‑scale Langfuse installations.

Managed Postgres vs. Self-Managed: Making the Database Call

Managed Postgres vs. Self‑Managed: Making the Database Call

Langfuse stores all transactional state—user accounts, projects, API keys, and other metadata—in PostgreSQL, accessed through the Prisma ORM [4]. Because this data is critical for durability and correctness, backup, point‑in‑time recovery, and patch management dominate the database‑related operational concerns. The heavy analytical workload (LLM trace ingestion, scoring, dashboards) runs in ClickHouse, so the PostgreSQL tier does not need to handle high‑throughput queries [4].

Two documented approaches

Approach	Typical providers / implementation	When it fits
Fully managed PostgreSQL	AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL	Teams that prefer low‑ops overhead. Managed services automatically provide automated backups, point‑in‑time recovery, version‑patching, and built‑in connection pooling [2].
Self‑managed PostgreSQL	PostgreSQL deployed as a StatefulSet on Kubernetes (or any self‑hosted VM)	Teams already operating Kubernetes clusters and needing full control over configuration, extensions, or cost‑optimization.

The Docker Compose stack bundles a PostgreSQL container for quick local testing, while the Helm chart v2.0.0 uses the community groundhog2k/postgres sub‑chart [1]. Setting postgres.deploy: false in values.yaml disables the bundled chart and lets the deployment point at an external connection string—a version‑sensitive option introduced with v2.0.0.

Sizing baseline

Langfuse documentation lists a minimum of 2 CPU and 4 GiB memory for the PostgreSQL service [9]. Larger workloads should provision proportionally more resources, especially if event volume approaches the ClickHouse tier’s limits.

Recommendation

Default to a managed PostgreSQL service unless one or more of the following applies:

• Strict data‑residency or compliance requirements that mandate on‑prem or private‑cloud storage.
• Existing expertise and tooling for operating PostgreSQL on Kubernetes.
• Cost considerations where the managed service price outweighs operational effort.

Managed services relieve the team that owns the database of backup tooling; the Docker Compose path does not ship any backup utilities, so operators must implement their own strategy if they stay with the bundled container.

ClickHouse side note

While PostgreSQL decisions are independent, the same “official vs. community” split exists for ClickHouse: the Langfuse team officially supports ClickHouse Cloud, BYOC, and the Kubernetes Operator, whereas the bundled Helm sub‑chart and single‑container Docker compose setup are community‑maintained options [13]. This parallel helps teams keep the same level of operational responsibility across both data stores.

Production Posture: High Availability, Sizing, and Ingestion Scaling

Production Posture: High Availability, Sizing, and Ingestion Scaling

High‑availability topology

• Deploy ≥ 2 Langfuse Web pods behind a Kubernetes Ingress (or an external load balancer).
• Keep session and request state outside the pods (PostgreSQL + Redis/Valkey) so a Web pod can fail without losing user context.
• The Langfuse Worker runs without exposed ports and can be scaled independently; it consumes the queued ingestion jobs.
• For seamless failover all pods should define readinessProbe and livenessProbe; the Ingress routes only to pods that report healthy.

Baseline resource profile (minimums from the official scaling guide)

Component	CPU	Memory
Langfuse Web	2 vCPU	4 GiB
Langfuse Worker	2 vCPU	4 GiB
PostgreSQL	2 vCPU	4 GiB
Redis/Valkey	1 vCPU	1.5 GiB
ClickHouse	2 vCPU	8 GiB (≥ 16 GiB advisable for larger workloads)
Blob storage (S3‑compatible or MinIO)	2 vCPU	4 GiB

These numbers are a starting point; production clusters should add headroom and enable Horizontal Pod Autoscaling (HPA) based on CPU ≈ 50 % or custom metrics.

Ingestion‑focused split
When ingest traffic dominates, the platform can be split into two distinct langfuse-web deployments:

1. UI deployment – serves the console and low‑volume API calls.
2. Ingestion deployment – handles /api/public/ingestion*, /api/public/media*, and /api/public/otel* endpoints.

Routing the heavy ingestion paths to the dedicated deployment prevents UI request latency from being starved by bursty write traffic. The split is safe because:

• Queued ingestion – the Web pod writes incoming batches directly to the configured blob store and posts only a reference to Redis, so database writes never block the request path.
• API‑key cache – keys are cached in Redis, allowing cheap reject of unauthorized calls.
• Prompt cache – prompts are cached read‑through in Redis and additionally in the client SDKs, eliminating repeated DB lookups.

Practical Kubernetes recommendations

• Ingress & TLS – use a real Ingress controller (e.g., NGINX, Traefik) with TLS termination instead of local port‑forwards.
• Resource requests/limits – set the values from the baseline table and add a safety margin (e.g., +30 %).
• Replica counts – start with replicas: 2 for the Web tier and configure HPA to add pods when CPU > 50 % or queue length grows.
• Health probes – define HTTP /healthz checks for both Web and Worker containers; the Ingress will only route to pods that pass.
• External state – verify that PostgreSQL, Redis/Valkey, ClickHouse, and blob storage are not hosted inside the same pod or PVC, otherwise pod restarts will cause data loss.

Following these guidelines yields a resilient, horizontally scalable Langfuse installation capable of handling production‑grade ingestion spikes without compromising UI responsiveness.

Sources: resource minimums, HA recommendation, ingestion split, queue & caching behavior.

A Decision Framework: Choosing the Right Path for Your Scale

A Decision Framework: Choosing the Right Path for Your Scale

Documented facts

• The Langfuse project ships two primary self‑hosting entry points: a Docker Compose stack for testing or low‑volume use, and a Helm chart for Kubernetes deployments. The Docker‑Compose option does not provide high‑availability, horizontal scaling, or built‑in backup mechanisms【5†L1-L4】.
• For production‑grade workloads, the Langfuse documentation lists Kubernetes (Helm) and the AWS/Azure/GCP Terraform templates as the official “production‑scale” options【5†L5-L9】. Community surveys note that VM‑based (non‑K8s) deployments rarely meet high‑traffic scalability requirements, with Kubernetes being the dominant pattern among large‑scale teams【5†L9-L11】.
• Helm chart v2.0.0 replaces all Bitnami sub‑charts with OSS‑licensed alternatives and sets Langfuse v4 as the default appVersion. Because the chart changes StatefulSet and PVC layouts, a direct helm upgrade from a v1 release that bundles stores is blocked; migration must be performed first【1†L1-L7】【3†L9-L13】.
• PostgreSQL backing stores can be either fully managed (e.g., AWS RDS, GCP Cloud SQL, Azure Database) or self‑hosted inside the Kubernetes cluster. The Langfuse team recommends managed instances for most teams to reduce operational overhead, reserving self‑management for cases with strict data‑residency, existing cluster expertise, or cost constraints【2†L1-L7】.
• The free OSS tier of Langfuse includes the deployment documentation and core platform features with unlimited usage, while the Enterprise tier adds project‑level RBAC, data‑retention policies, audit logs, management APIs, and optional ClickHouse Cloud/BYOC/Private bundles【8†L1-L6】.

Recommendations

• Start with Docker Compose when you need a quick evaluation, have a small team, or expect low ingestion volumes, and you can accept the documented gaps (no HA, no scaling, no backups).
• Move to Kubernetes with the Helm chart as soon as any of the following become non‑negotiable: availability SLAs, horizontal scaling, or integration with backup tooling. Helm + Terraform templates are the officially supported production pathways, and they align with the most common high‑scale patterns.
• Adopt chart v2.0.0 early if you plan to upgrade to Langfuse v4. Its fully OSS‑licensed bundle removes licensing risk and provides the required ClickHouse version. Perform the chart v1→v2 migration before the v4 application upgrade to avoid incompatibilities.
• Prefer a managed PostgreSQL instance unless you have compelling residency, existing operations, or cost‑control reasons to run it yourself. Managed services handle backups, patching, and failover out of the box.
• Staged adoption path:
  1. Pilot on Docker Compose.
  2. Once stability and basic feature fit are confirmed, provision external managed stores (Postgres, ClickHouse, Valkey).
  3. Deploy the v2.0.0 Helm chart, pin chart and app versions, and treat the chart migration and the Langfuse v4 upgrade as separate change windows.

Following this framework lets teams align infrastructure complexity with actual scale requirements while minimizing licensing exposure and operational risk.

Methodology and sources

• Reviewed: October 21, 2026.
• Method: Documentation-led analysis using the primary sources listed below. Validate versions and environment-specific claims before production use.
• Langfuse Self-Hosting Documentation
• Langfuse Docker Compose Deployment Guide
• Langfuse Kubernetes Helm Deployment Guide
• Langfuse Helm Chart v1 to v2 Upgrade Guide
• Langfuse Container Infrastructure Documentation
• Langfuse Scaling and Configuration Documentation
• Langfuse ClickHouse Infrastructure Documentation
• Langfuse Self-Host Pricing