Developer Quickstart

GitHub

Run the latest self-hosted Langfuse locally with a single Docker Compose stack.

35m10m reading25m lab

Developer Quickstart

Use this lesson when you want the fastest path to a working self-hosted Langfuse setup on one machine.

By the end of this guide, you will have:
  • the Langfuse web UI running on http://localhost:3000
  • the worker, Postgres, ClickHouse, Redis, and MinIO containers running together
  • a local stack ready for SDK tracing experiments
Use this setup when:
  • you want a fast local sandbox
  • you are validating SDK integration in an application
  • you want a lightweight proof of concept on one machine
  • you need one Compose file with inline defaults for quick testing
Do not treat this setup as production-ready. It is intentionally optimized for quick local evaluation, not for long-term operations.

What You Are Running

This quickstart brings up six services:
  • Langfuse web for the browser UI and application endpoints
  • Langfuse worker for background jobs and async processing
  • Postgres for transactional application data
  • ClickHouse for analytics and event-heavy workloads
  • Redis for caching and queue coordination
  • MinIO for S3-compatible object storage
At a high level, the stack looks like this: 

Application SDKs
	   |
	   v
   Langfuse Web  <---->  Langfuse Worker
	   |                     |
	   |                     +--> Redis
	   |                     +--> ClickHouse
	   |
	   +--> Postgres
	   +--> MinIO

Two details matter for understanding the setup:
  • CLICKHOUSE_CLUSTER_ENABLED: false keeps ClickHouse in standalone mode for one machine
  • Postgres stores transactional data while ClickHouse stores analytics-oriented data

Project Files

langfuse-developer-quickstart
Explorer
docker-compose.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
services:
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:latest
    container_name: langfuse-worker
    restart: unless-stopped
    depends_on: &langfuse-depends-on
      postgres:
        condition: service_healthy
      minio:
        condition: service_healthy
      redis:
        condition: service_healthy
      clickhouse:
        condition: service_healthy
    environment: &langfuse-env
      NEXTAUTH_URL: http://localhost:3000
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
      SALT: developer-quickstart-salt
      ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
      TELEMETRY_ENABLED: false
      CLICKHOUSE_MIGRATION_URL: clickhouse://clickhouse:9000
      CLICKHOUSE_URL: http://clickhouse:8123
      CLICKHOUSE_USER: clickhouse
      CLICKHOUSE_PASSWORD: clickhouse
      CLICKHOUSE_CLUSTER_ENABLED: false
      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
      LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: minio
      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: miniosecret
      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://minio:9000
      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: true
      LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
      LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
      LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: minio
      LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: miniosecret
      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: http://minio:9000
      LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: true
      LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_AUTH: myredissecret

  langfuse-web:
    image: docker.io/langfuse/langfuse:latest
    container_name: langfuse-web
    restart: unless-stopped
    depends_on: *langfuse-depends-on
    ports:
      - 3000:3000
    environment:
      <<: *langfuse-env
      NEXTAUTH_SECRET: developer-quickstart-secret

  clickhouse:
    image: docker.io/clickhouse/clickhouse-server:latest
    container_name: langfuse-clickhouse
    restart: unless-stopped
    user: "101:101"
    environment:
      CLICKHOUSE_DB: default
      CLICKHOUSE_USER: clickhouse
      CLICKHOUSE_PASSWORD: clickhouse
    volumes:
      - langfuse_quickstart_clickhouse_data:/var/lib/clickhouse
      - langfuse_quickstart_clickhouse_logs:/var/log/clickhouse-server
    ports:
      - 127.0.0.1:8123:8123
      - 127.0.0.1:9000:9000
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 1s

  minio:
    image: cgr.dev/chainguard/minio:latest
    container_name: langfuse-minio
    restart: unless-stopped
    entrypoint: sh
    command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
    environment:
      MINIO_ROOT_USER: minio
      MINIO_ROOT_PASSWORD: miniosecret
    ports:
      - 9090:9000
      - 127.0.0.1:9091:9001
    volumes:
      - langfuse_quickstart_minio_data:/data
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 1s
      timeout: 5s
      retries: 5
      start_period: 1s

  redis:
    image: docker.io/redis:latest
    container_name: langfuse-redis
    restart: unless-stopped
    command: >
      --requirepass myredissecret
      --maxmemory-policy noeviction
    ports:
      - 127.0.0.1:6379:6379
    volumes:
      - langfuse_quickstart_redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 3s
      timeout: 10s
      retries: 10

  postgres:
    image: docker.io/postgres:latest
    container_name: langfuse-postgres
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
      TZ: UTC
      PGTZ: UTC
    ports:
      - 127.0.0.1:5432:5432
    volumes:
      - langfuse_quickstart_postgres_data:/var/lib/postgresql

volumes:
  langfuse_quickstart_postgres_data:
    driver: local
  langfuse_quickstart_clickhouse_data:
    driver: local
  langfuse_quickstart_clickhouse_logs:
    driver: local
  langfuse_quickstart_minio_data:
    driver: local
  langfuse_quickstart_redis_data:
    driver: local
YAMLUTF-8
Ln 1461 files

Before You Start

You only need Docker Compose and a machine with enough memory to run six containers comfortably.

The Compose file exposes these local entry points:
  • Langfuse UI at http://localhost:3000
  • MinIO S3 API at http://localhost:9090
  • MinIO Console at http://localhost:9091
  • Postgres at 127.0.0.1:5432
  • Redis at 127.0.0.1:6379
  • ClickHouse HTTP at 127.0.0.1:8123
Before you launch the stack:
  • make sure ports 3000, 5432, 6379, 8123, 9090, and 9091 are free on your machine
  • expect the images to use latest tags
  • expect inline local credentials inside the Compose file

Deploy

  1. 1 Use Download All in the Project Files section above to save docker-compose.yml into a new folder, for example langfuse-developer-quickstart/
  2. 2 Open a terminal in that folder
  3. 3 Start the full stack 
docker compose up -d

Then confirm that all containers came up:

docker compose ps

Expected services:

NAME                  STATUS
langfuse-postgres     running (healthy)
langfuse-clickhouse   running (healthy)
langfuse-redis        running (healthy)
langfuse-minio        running (healthy)
langfuse-worker       running
langfuse-web          running
If some services are still starting, wait a few seconds and run docker compose ps again. Langfuse depends on the backing services becoming healthy first.

Verify

Open http://localhost:3000 in your browser. The Langfuse web app should load after Postgres, Redis, ClickHouse, and MinIO report healthy and the startup sequence finishes.

Use this quick verification order:
  1. 1 Check docker compose ps
  2. 2 Open the UI in the browser
  3. 3 If the UI is not ready, inspect the web and worker logs
If the UI is still starting, inspect the web and worker logs: 

docker compose logs langfuse-web --tail 50
docker compose logs langfuse-worker --tail 50

You can also probe the dependencies directly: 

curl http://127.0.0.1:8123/ping
redis-cli -a myredissecret ping

Expected response: 
Ok
PONG

Configuration Defaults

This quickstart is deliberately self-contained. The Compose file includes inline defaults so you can copy, run, and test immediately:

NEXTAUTH_URL: http://localhost:3000
DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
NEXTAUTH_SECRET: developer-quickstart-secret
SALT: developer-quickstart-salt
ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
REDIS_AUTH: myredissecret
MINIO_ROOT_USER: minio
MINIO_ROOT_PASSWORD: miniosecret
⚠️

Warning: Replace these defaults before using this stack anywhere beyond local experimentation.

The main trade-offs are straightforward:
  • fast to start because everything is inline
  • easy to demo because there is one Compose file
  • not hardened because secrets, image tags, and storage choices are tuned for convenience

What This Guide Does Not Solve

This page is intentionally not trying to cover:
  • high availability
  • external secret management
  • backup and restore workflows
  • production hardening
Those topics belong in a larger single-node or production course path later.

Common Issues

Port already in use

The stack binds several local ports. If one is already taken, the containers may fail to start cleanly.

lsof -i :3000
lsof -i :5432
If one is busy, change the published port in docker-compose.yml and start the stack again.

Web UI does not open yet

Langfuse waits for Postgres, MinIO, Redis, and ClickHouse health checks before the app becomes usable.

docker compose ps
docker compose logs postgres --tail 50
docker compose logs clickhouse --tail 50
Wait until the dependency containers report healthy, then reload the page.

You want a cleaner setup for team use

This quickstart is intentionally simpler than a hardened single-node deployment:
  • credentials are inline
  • image tags track latest
  • there is no backup or restore workflow
  • there is no external secret management
Use it for local evaluation, not as a production baseline.

Next Step

  • Repoint your application SDK to http://localhost:3000 and start sending local traces into this stack
  • Return to the course overview if you want the higher-level context for this setup