• September 27, 2026
• 5 min read

Langfuse — Setup & Architecture¶

Cloud vs Self-Hosted¶

Self-Hosting Architecture¶

flowchart LR
  SDK["Python SDK / OTLP exporters"] -- "HTTPS /api/public/*" --> WEB["langfuse-web<br/>UI + public API :3000"]
  UI["Browser"] --> WEB
  WEB -- "raw events" --> S3[("S3 / MinIO<br/>events, media, exports")]
  WEB -- "enqueue" --> REDIS[("Redis / Valkey<br/>queues + cache")]
  REDIS --> WORKER["langfuse-worker<br/>async processing :3030"]
  WORKER --> S3
  WORKER --> CH[("ClickHouse<br/>traces, observations, scores")]
  WEB --> PG[("Postgres<br/>users, projects, prompts, datasets")]
  WORKER --> PG
  WEB --> CH
  WORKER -. "LLM-as-a-judge, playground" .-> LLM["LLM API / gateway"]

Ingestion is asynchronous: the API accepts the batch, stores the raw event in S3, enqueues it, and the worker writes it to ClickHouse. Expect a delay of a few seconds before a trace is queryable — important when tests read traces back.

Docker Compose Quick Start¶

git clone https://github.com/langfuse/langfuse.git
cd langfuse
# edit every line marked "# CHANGEME" in docker-compose.yml (or override via .env)
docker compose up -d
docker compose ps          # web, worker, postgres, clickhouse, redis, minio
open http://localhost:3000 # sign up → create org → create project → API keys

• Compose is for local and test use: single VM, no HA. For production use the Helm chart or the cloud Terraform modules.
• VM sizing for Compose: at least 4 cores, 16 GiB RAM, ~100 GiB disk.
• Secrets to replace: SALT, ENCRYPTION_KEY (openssl rand -hex 32), NEXTAUTH_SECRET, DB/ClickHouse/Redis/MinIO passwords.
• NEXTAUTH_URL must match the URL users type in the browser.

Headless initialization (ephemeral CI instance)¶

The web container can create an org, project, user and API keys on first start — useful for a throwaway Langfuse in a CI job:

# .env next to docker-compose.yml
LANGFUSE_INIT_ORG_ID=qa-org
LANGFUSE_INIT_ORG_NAME=QA
LANGFUSE_INIT_PROJECT_ID=llm-tests
LANGFUSE_INIT_PROJECT_NAME=llm-tests
LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-ci-local
LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-lf-ci-local
LANGFUSE_INIT_USER_EMAIL=qa@example.com
LANGFUSE_INIT_USER_NAME=qa
LANGFUSE_INIT_USER_PASSWORD=change-me-please

docker compose up -d
until curl -fsS http://localhost:3000/api/public/health; do sleep 2; done
export LANGFUSE_BASE_URL=http://localhost:3000
export LANGFUSE_PUBLIC_KEY=pk-lf-ci-local LANGFUSE_SECRET_KEY=sk-lf-ci-local

SDK Environment Variables¶

The same settings are constructor arguments when you need them in code:

from langfuse import Langfuse

langfuse = Langfuse(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    base_url="http://localhost:3000",
    environment="ci",
    release="a1b2c3d",
    sample_rate=1.0,
)
assert langfuse.auth_check(), "Langfuse keys or base URL are wrong"

Organizations, Projects, API Keys¶

Organization (billing, members, SSO)
 └── Project  (traces, prompts, datasets, scores, API keys, retention)
      ├── Public key  pk-lf-…   identifies the project (safe in browser for feedback scores)
      └── Secret key  sk-lf-…   full API access — backend and CI secrets only

• API keys are per project; data never crosses projects.
• Create a dedicated key pair per consumer (app, CI, notebook) so you can rotate one without breaking the others.
• Public API authentication is HTTP Basic: public_key:secret_key.

curl -s -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_BASE_URL/api/public/traces?limit=5&tags=ci" | jq '.data[].id'

RBAC¶

• Roles are assigned at organization level and inherited by projects.
• Project-level roles (override per project) require Pro + Teams add-on, Enterprise, or self-hosted Enterprise Edition.
• Typical QA setup: QA engineers are Member on the test project (create datasets, annotate) and Viewer on production.

See also¶

• Langfuse — LLM Tracing, Prompts & Evals
• Langfuse — Tracing with the Python SDK
• Docker & Docker Compose — Compose
• OpenTelemetry — Python Observability
• Arize Phoenix