Part 2 covered what the data model and storage are. This lesson closes it with what it takes to run — to
self-host Langfuse, which containers you actually start and how they connect. The answer is clean: 2 app containers + 4
infrastructure engines, all in the root docker-compose.yml. Land the abstract architecture of earlier lessons onto this
concrete "packing list" and your mental model of Langfuse's "shape" is complete.
🔌 Analogy
Picture a Langfuse deployment as the rooms a restaurant needs: the front of house (web) greets guests, shows the menu,
serves dishes; the kitchen (worker) quietly preps, washes up, handles big orders; the cold storage
(ClickHouse) holds mountains of ingredients (telemetry); the filing cabinet (Postgres) keeps the menu and staff records
(config); the order pass (Redis) queues tickets; the warehouse (S3/MinIO) stacks big, rarely-used stock
(manuscripts, media). Miss a room and the restaurant limps — but assemble these 6 and you can open for business.
The self-host packing list: two app containers langfuse-web (langfuse/langfuse:3) and langfuse-worker (langfuse/langfuse-worker:3), plus four infra postgres:17 · clickhouse-server · redis:7 · minio (S3-compatible). Each infra gets a named volume for persistence. This is the "physical version" of the architecture in Lessons 5 and 7.
Three tiers, scaled per tier (per docker-compose/helm and server/queues.ts): stateless web and worker each run multiple replicas and scale independently (web for user traffic, worker for queue backlog); stateful Postgres/ClickHouse/Redis/S3 sit underneath, shared by both. This is Lessons 5 and 7's "read/write split, four-store division of labor" landed on containers.
The minimal self-host stack: 2 apps + 4 infra
Service
Image
Role
langfuse-web
langfuse/langfuse:3
user-facing: UI + tRPC + public REST API (ingestion entry)
S3-compatible object store (local stand-in): event log · media · exports
Note minio: an open-source object store that speaks the S3 protocol, standing in for AWS S3 locally / when
self-hosting. So the same code uses real S3 in the cloud and MinIO when self-hosted, entirely transparent to the app layer —
the portability of "program to an interface (the S3 protocol), not an implementation". The four infra containers each mount a named
volume for persistence (postgres / clickhouse data+logs / redis / minio), while web and worker are stateless — no volumes;
so docker compose down then up keeps your data.
app tierweb · worker
stateless business containers, restartable and scalable on demand. They start, connect to the storage below, and work.
data tierpostgres · clickhouse
two databases: control plane (config) and data plane (telemetry). Stateful, persisted via named volumes — the bedrock.
support tierredis · minio
queue/cache and object store. Make ingestion async and give big fields/media a home. Also stateful, also persisted.
These tiers have a plain startup order: bring up the data and support tiers and wait for them to be healthy, then start the app
tier — so in compose the app containers depends_on the infra and wait for healthchecks. Grasp this layering and you have
direction when debugging deployments: can't reach the DB → check the data tier; ingestion stalled → check Redis; media won't save → check
MinIO.
web and worker: division and collaboration
The two app containers are Langfuse's "two hands". Similar in form (both connect the same storage) but opposite in
duty:
Two hands: web is user-facing, low-latency, restartable; worker chews heavy jobs, retryable, scales by queue backlog. The two are decoupled by the Redis queue (L05), so you scale them separately — more users, add web; backed-up queue, add worker. This is the deployment-side expression of Lesson 4's "narrow waist" letting the two containers evolve independently.
scaling web
stateless, request-facing → watch concurrent users / QPS, run a few replicas behind a load balancer.
scaling worker
queue-facing → watch queue backlog, spin up more worker instances to consume (and shard by queue, L14).
Configuration is all environment variables
How do the six containers know each other's addresses, secrets and toggles? Environment variables. The repo has a set of
.env.*.example templates (e.g. .env.dev.example, .env.prod.example) listing every variable to set (DB
connections, S3 endpoint, encryption keys…). More importantly, these envs aren't read loosely — they pass through Zod
validation (packages/shared/src/env.ts, worker/src/env.ts, etc.), checking types and required fields at
startup. Misconfigure or miss one and the process fails to start and tells you exactly which variable is wrong, rather
than running sick and crashing midway. This "validate config at startup" discipline turns "config errors" from hard-to-find
runtime bugs into obvious startup errors (expanded in L51).
Put it together and the first self-host experience is actually simple: clone the repo → copy an .env.dev.example and fill
the key variables → docker compose up, and the six containers come up in dependency order, connect, and within minutes you
open a browser to the Langfuse UI. The repo also ships several compose files for different scenarios —
docker-compose.dev.yml (local dev, often just the infra while the apps run on your machine for hot reload),
docker-compose.yml (the full stack), and cloud-specific variants (e.g. Azure). This "one orchestration for the whole
stack, variants per scenario" is exactly how the earlier "four-dependency complexity" gets folded into a few yml files — you needn't
hand-install each database or wire the network; compose strings it all together. Grasp this topology and you'll not only "get it running" but
also know which container's logs to check when something breaks.
.env.dev.example (excerpt, grouped by "4 infra + auth")config = wiring
# ① Postgres — metadata: config/users/permissions (L07 OLTP)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"# ② ClickHouse — massive trace/observation/score events (L08 columnar)
CLICKHOUSE_URL="http://localhost:8123"
CLICKHOUSE_USER="clickhouse" CLICKHOUSE_PASSWORD="clickhouse"# ③ Redis — ingestion queue + cache (where L12's "receive fast" lands)
REDIS_HOST=localhost REDIS_PORT=6379
# ④ S3 / MinIO — bulky payloads & media (L18); MinIO is a local S3 stand-in
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_..._ENDPOINT="http://localhost:9090" ..._FORCE_PATH_STYLE=true# auth & secrets — Zod-validated at startup, miss one = fail to start (L51)
NEXTAUTH_URL="http://localhost:3000" NEXTAUTH_SECRET="secret"
SALT="salt"// salt for API-key hashing (L49 createShaHash)
🎯 Design trade-off
Are four infra dependencies a burden for self-hosters? Honestly, yes — versus "one binary + one SQLite", Langfuse's
self-host bar is genuinely higher. But that's the deployment-side consequence of Lesson 7's trade-off: to handle
production scale (massive telemetry, async ingestion, object storage), none of the four is droppable. Langfuse's mitigation is bringing up
all six containers with one docker-compose command and using a MinIO stand-in to remove the dependency on
cloud S3, making "run the whole thing on your own machine" easy. Complexity can't be erased, but it can be packaged and delivered in
one command. That's why the docs say "self-host in minutes" — not no dependencies, but dependencies orchestrated for you.
🎯 Key points · Part 2 wrap-up
Minimal self-host stack = 2 apps + 4 infra: langfuse-web + langfuse-worker, plus postgres · clickhouse · redis · minio(S3), all in docker-compose.yml.
web vs worker: same storage, opposite duties — web user-facing/low-latency, scales by QPS; worker heavy/retryable, scales by queue backlog; decoupled by the Redis queue.
MinIO is an S3-protocol stand-in: same code uses real S3 in the cloud, MinIO locally — transparent to the app.
Config is all env vars, Zod-validated at startup (env.ts) — misconfigure and it fails to start with a clear message, no sick running.
Four deps are the necessary cost of scale (L07), mitigated by one-command docker-compose orchestration — "plenty of deps, but packaged".
🧪 Self-test - think about the design
1. What containers make up the minimal stack to self-host Langfuse?
Only ClickHouse
web + worker + one SQLite file
Just one langfuse container
2 apps (langfuse-web, langfuse-worker) + 4 infra (postgres, clickhouse, redis, minio/S3), all in docker-compose.yml
Show answer & explanation click to expand
Answer: D. docker-compose.yml lists two app containers (web/worker) plus four infra (postgres:17, clickhouse-server, redis:7, minio). It's the physical version of the architecture in L05/L07.
2. web and worker connect the same storage — why split into two containers, and why scale them separately?
Because one container can't hold the code
Opposite duties: web is user-facing, low-latency, scales by QPS; worker chews heavy jobs, retryable, scales by queue backlog. Decoupled by the Redis queue, so each scales independently without blocking the other
Because they use different databases
Just to run more machines
Show answer & explanation click to expand
Answer: B. User pressure (QPS) and background pressure (queue backlog) are independent scaling signals. Splitting into two containers decoupled by a queue lets you 'add web for more users, add worker for a backed-up queue', without entanglement. It's the deployment-side expression of L04's narrow waist.
3. Langfuse validates env vars with Zod 'at startup'. What's the benefit of this discipline?
To make startup slower for checking
To auto-fix wrong config
To encrypt env vars
A misconfig/missing var makes the process fail to start and names the bad variable — turning 'config errors' from hard-to-find runtime bugs into obvious startup errors, instead of running sick and crashing midway
Show answer & explanation click to expand
Answer: D. Fail-fast: env.ts uses Zod to validate types and required fields at startup, reporting clearly on error. Far more debuggable than 'running with bad config and crashing in some corner feature later' (expanded in L51).
💭 Open questions (no single right answer - just think or try)
Langfuse self-host needs 4 infra engines, a higher bar than 'one binary'. If you built an open-source tool, how would you trade off 'handles scale' vs 'easy to self-host'? Is one-command docker-compose orchestration a good answer?