# Langfuse Self-Hosting — Production Docker Compose Stack

> Production Docker Compose for self-hosted Langfuse v3. Postgres, Clickhouse, Redis, MinIO, Worker, Web. Auth, S3 logs, daily backup.

## Install

Copy the content below into your project:

## Quick Use

1. Copy docker-compose.yml + .env from langfuse/langfuse repo
2. Generate NEXTAUTH_SECRET (`openssl rand -hex 32`)
3. `docker compose up -d`, open localhost:3000

---

## Intro

This is a production-ready docker-compose stack for self-hosting Langfuse v3 — Postgres, Clickhouse, Redis, MinIO, Worker, and Web behind a single docker-compose up. Includes SSO config snippets (Google, Okta, GitHub OAuth), S3 log offloading, daily Postgres backup cron, and scaling notes for >1M observations/day workloads. Best for: teams handling sensitive prompt data who can't ship to Langfuse Cloud — healthcare, finance, on-prem regulated environments. Works with: any Linux host with Docker 24+. Setup time: 30 minutes from zero to first trace.

---

### docker-compose.yml core

```yaml
services:
  langfuse-web:
    image: langfuse/langfuse:3
    environment:
      DATABASE_URL: postgresql://lf:${POSTGRES_PASSWORD}@postgres:5432/langfuse
      CLICKHOUSE_URL: http://clickhouse:8123
      CLICKHOUSE_USER: lf
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      REDIS_URL: redis://redis:6379
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXTAUTH_URL: https://langfuse.example.com
      AUTH_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
      AUTH_GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse-events
      LANGFUSE_S3_EVENT_UPLOAD_REGION: us-east-1
    ports: ["3000:3000"]
    depends_on: [postgres, clickhouse, redis, minio]

  langfuse-worker:
    image: langfuse/langfuse-worker:3
    environment: # same as web
      DATABASE_URL: postgresql://lf:${POSTGRES_PASSWORD}@postgres:5432/langfuse
      CLICKHOUSE_URL: http://clickhouse:8123
      REDIS_URL: redis://redis:6379

  postgres:
    image: postgres:16
    volumes: ["pgdata:/var/lib/postgresql/data"]
    environment:
      POSTGRES_USER: lf
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: langfuse

  clickhouse:
    image: clickhouse/clickhouse-server:24
    volumes: ["chdata:/var/lib/clickhouse"]
    environment:
      CLICKHOUSE_USER: lf
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}

  redis:
    image: redis:7-alpine

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    volumes: ["miniodata:/data"]

volumes: { pgdata: {}, chdata: {}, miniodata: {} }
```

### Daily Postgres backup

```cron
0 2 * * * docker exec postgres pg_dump -U lf langfuse | gzip > /backup/lf-$(date +\%F).sql.gz
0 3 * * * find /backup -name "lf-*.sql.gz" -mtime +30 -delete
```

### Scaling thresholds

| Workload | Setup |
|---|---|
| <100K observations/day | Single-node compose, default sizing |
| 100K–1M | Move Clickhouse to a 4-core / 16GB box, separate Redis |
| 1M–10M | Multi-replica web/worker, managed Clickhouse cluster, S3 for events |
| >10M | Talk to Langfuse Enterprise |

### Health checks

```bash
curl -f https://langfuse.example.com/api/public/health  # web
docker exec clickhouse clickhouse-client -q "SELECT count() FROM traces"
```

---

### FAQ

**Q: How does Langfuse v3 differ from v2 for self-hosters?**
A: v3 introduced Clickhouse for traces (v2 used Postgres only), MinIO/S3 for event uploads, and a separate worker service. Migration guide is in the repo. v3 handles 10× the observation volume on the same hardware.

**Q: Do I need MinIO if I'm small?**
A: Below 100K observations/day, no — Langfuse falls back to direct DB writes. MinIO is the queue for high-volume event ingestion. For prod scale or cloud parity, run it. For dev, omit.

**Q: What about TLS and reverse proxy?**
A: Run Caddy or nginx in front. Caddy auto-issues Let's Encrypt: `langfuse.example.com { reverse_proxy langfuse-web:3000 }` — that's it. NEXTAUTH_URL must match the public HTTPS URL or Google OAuth redirects break.

---

## Source & Thanks

> Built by [Langfuse](https://github.com/langfuse). Licensed under MIT.
>
> [langfuse/langfuse](https://github.com/langfuse/langfuse) — ⭐ 8,000+

---

<!-- ZH -->

## 快速使用

1. 从 langfuse/langfuse 仓库复制 docker-compose.yml + .env
2. 生成 NEXTAUTH_SECRET（`openssl rand -hex 32`）
3. `docker compose up -d`，打开 localhost:3000

---

## 简介

这是 Langfuse v3 自托管的生产级 docker-compose 栈 —— Postgres、Clickhouse、Redis、MinIO、Worker、Web，一句 docker-compose up 起。含 SSO 配置片段（Google / Okta / GitHub OAuth）、S3 日志卸载、每日 Postgres 备份 cron、单日 100 万观测以上工作负载的扩容笔记。适合不能上云的敏感 prompt 数据团队 —— 医疗、金融、本地化合规环境。兼容任何 Docker 24+ 的 Linux 主机。装机时间：30 分钟从 0 到第一条 trace。

---

### docker-compose.yml 核心

```yaml
services:
  langfuse-web:
    image: langfuse/langfuse:3
    environment:
      DATABASE_URL: postgresql://lf:${POSTGRES_PASSWORD}@postgres:5432/langfuse
      CLICKHOUSE_URL: http://clickhouse:8123
      CLICKHOUSE_USER: lf
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
      REDIS_URL: redis://redis:6379
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      NEXTAUTH_URL: https://langfuse.example.com
      AUTH_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
      AUTH_GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse-events
      LANGFUSE_S3_EVENT_UPLOAD_REGION: us-east-1
    ports: ["3000:3000"]
    depends_on: [postgres, clickhouse, redis, minio]

  langfuse-worker:
    image: langfuse/langfuse-worker:3
    environment: # 同 web
      DATABASE_URL: postgresql://lf:${POSTGRES_PASSWORD}@postgres:5432/langfuse
      CLICKHOUSE_URL: http://clickhouse:8123
      REDIS_URL: redis://redis:6379

  postgres:
    image: postgres:16
    volumes: ["pgdata:/var/lib/postgresql/data"]
    environment:
      POSTGRES_USER: lf
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: langfuse

  clickhouse:
    image: clickhouse/clickhouse-server:24
    volumes: ["chdata:/var/lib/clickhouse"]
    environment:
      CLICKHOUSE_USER: lf
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}

  redis:
    image: redis:7-alpine

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    volumes: ["miniodata:/data"]

volumes: { pgdata: {}, chdata: {}, miniodata: {} }
```

### 每日 Postgres 备份

```cron
0 2 * * * docker exec postgres pg_dump -U lf langfuse | gzip > /backup/lf-$(date +\%F).sql.gz
0 3 * * * find /backup -name "lf-*.sql.gz" -mtime +30 -delete
```

### 扩容阈值

| 工作负载 | 配置 |
|---|---|
| 单日 <10 万观测 | 单节点 compose，默认配置 |
| 10 万–100 万 | Clickhouse 移到 4 核/16GB 独立机器，Redis 单独跑 |
| 100 万–1000 万 | web/worker 多副本，Clickhouse 托管集群，事件用 S3 |
| >1000 万 | 找 Langfuse 企业版 |

### 健康检查

```bash
curl -f https://langfuse.example.com/api/public/health  # web
docker exec clickhouse clickhouse-client -q "SELECT count() FROM traces"
```

---

### FAQ

**Q: Langfuse v3 和 v2 自托管者的区别？**
A: v3 引入 Clickhouse 存 trace（v2 仅 Postgres）、MinIO/S3 存事件上传、worker 服务独立。仓库里有迁移指南。同样硬件 v3 能扛 10 倍观测量。

**Q: 规模小要 MinIO 吗？**
A: 单日 <10 万观测不要 —— Langfuse 回退到直写 DB。MinIO 是高量事件入库的队列。生产规模或要跟云端对齐就跑，开发环境可省。

**Q: TLS 和反代怎么搞？**
A: 前面架 Caddy 或 nginx。Caddy 自动签 Let's Encrypt：`langfuse.example.com { reverse_proxy langfuse-web:3000 }` 就完事。NEXTAUTH_URL 必须和公网 HTTPS URL 一致，否则 Google OAuth 跳转炸。

---

## 来源与感谢

> Built by [Langfuse](https://github.com/langfuse). Licensed under MIT.
>
> [langfuse/langfuse](https://github.com/langfuse/langfuse) — ⭐ 8,000+


---
Source: https://tokrepo.com/en/workflows/langfuse-self-hosting-production-docker-compose-stack
Author: Langfuse