# Langfuse Deployment

> Operating a self-hosted Langfuse deployment — architecture, sizing, scaling, backups, upgrades, and security. Use whenever the user is running or planning to run Langfuse on their own infrastructure: "operate / run self-hosted Langfuse", "deploy Langfuse on Kubernetes / Docker / AWS / GCP / Azure", "Langfuse sizing / resource requirements", "scale Langfuse / ingestion throughput", "back up Langfuse", "upgrade Langfuse / background migrations", "Langfuse SSO / encryption / VPC / air-gapped", or "Langfuse production deployment". Owns HOW to run self-hosted Langfuse well; the self-host-vs-Cloud and tier decision lives in the `langfuse-setup` skill, and exact configs in live docs.

- Skill: `jbaham2/langfuse-deployment` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add jbaham2/langfuse-deployment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jbaham2/langfuse-deployment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: jbaham2 (https://skillmd.com/u/jbaham2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jbaham2/langfuse-deployment

---


# Langfuse Deployment (self-hosted)

This skill covers operating self-hosted Langfuse: what to run, how big, how to scale it, and how to
keep it backed up, upgraded, and secure. It does **not** make the self-host-vs-Cloud or tier decision
(that's `langfuse-setup`'s `cloud-vs-self-host.md`) and does not embed exact compose/Helm/Terraform
config (fetch live `/self-hosting/*` docs).

## Operating principles

1. **Distill judgment, fetch facts.** This skill carries sizing/scaling/ops/security *judgment*. For
   exact config — env vars, Helm values, compose files, per-provider SSO — append `.md` to the live
   page URL (e.g. `https://langfuse.com/self-hosting/configuration/scaling.md`). Self-hosting config
   changes; never reconstruct it from memory.
2. **Prefer managed services.** Postgres, Redis, S3 (and optionally ClickHouse Cloud) as managed
   services give you encryption-at-rest, backups, and HA for free. Self-running all storage is the
   most operational burden — reserve it for air-gap/compliance needs.
3. **ClickHouse is the bottleneck and the hardest to operate.** Give it headroom first; if you
   self-run it, you own its (non-trivial) backups.

## Workflow

### 1. Confirm the decision is made
The self-host-vs-Cloud choice and the tier (Compose / Helm / Terraform / Railway) belong to
`langfuse-setup`. If that's unsettled, start there. This skill assumes "we're self-hosting" and helps
run it.

### 2. Architecture & sizing
Use `references/architecture-and-sizing.md`: the components (Web + Worker + Postgres/ClickHouse/
Redis/S3), the minimum-sizing table, HA (≥2 Web), managed-vs-self-run, single-vs-multi deployment
strategy, and the UTC requirement.

### 3. Scale for throughput
When ingestion or UI load grows, use `references/scaling.md`: scale workers by CPU (~50% = saturated),
reduce ClickHouse ingestion reads, separate ingestion from UI, raise S3 write concurrency; fix slow
UI via ClickHouse resources + time filters.

### 4. Operate it (backups, upgrades, DR)
Use `references/operations.md`: per-component backups (test restores!), semver/pinned-tag upgrade
discipline, and the background-migrations rule (monitor to completion after every upgrade).

### 5. Secure it
Use `references/security.md`: HTTPS, at-rest encryption, `ENCRYPTION_KEY`, networking (VPC/air-gap),
auth/SSO (`NEXTAUTH_URL` first), data masking at source, EE license; plus the pre-production security
checklist.

## Bundled resources

- **`references/architecture-and-sizing.md`** — components, minimum sizing, HA, managed-vs-self-run,
  single-vs-multi strategy, UTC.
- **`references/scaling.md`** — ingestion model and throughput levers; slow-query causes.
- **`references/operations.md`** — per-component backups, versioning, upgrades + background
  migrations, health/readiness, DR checklist.
- **`references/security.md`** — encryption, networking, auth/SSO, data masking, EE license, security
  checklist.

## Hand-off map

| Need | Where |
|------|-------|
| Run/scale/back-up/secure self-hosted Langfuse | this skill |
| Self-host-vs-Cloud decision + tier choice + onboarding | `langfuse-setup` skill |
| Instrumenting apps that send to this deployment | vendored `langfuse` skill |
| Monitoring the deployment's own load (dashboards) | `langfuse-monitoring` skill + `/self-hosting/configuration/observability` |
| Exact compose/Helm/Terraform/env/SSO config | live `/self-hosting/*` docs (`.md`-append) |