How to Install Langfuse: Self-Hosted Docker Setup and Local Development Guide

The fastest way to install Langfuse is to clone the repository, copy the example environment file, and run docker compose up to launch the full stack on localhost:3000.

This guide covers the complete installation process for Langfuse's self-hosted deployment, including the Docker Compose architecture, environment configuration, and optional local development setup. Whether you're running production workloads or contributing to the open-source project, you'll find the exact commands and file references needed to get started.

---

Self-Hosted vs. Cloud Deployment Options

Langfuse offers two primary installation paths. The self-hosted option runs entirely on your infrastructure using Docker Compose, giving you full control over data and configuration. The managed cloud service at cloud.langfuse.com requires no installation and handles scaling automatically.

This guide focuses on the self-hosted installation, which is the recommended approach for teams with data residency requirements or those wanting to customize the platform.

---

Prerequisites for Installing Langfuse

Before running the installation commands, ensure your system meets these requirements:

• Docker and Docker Compose installed and running
• Git for cloning the repository
• OpenSSL (optional) for generating secure encryption keys
• pnpm (optional) only if running the development environment

The self-hosted deployment consumes approximately 4–6 GB of RAM when running all services. For production use, allocate additional resources for the ClickHouse and PostgreSQL databases.

---

Step-by-Step Langfuse Installation Guide

Step 1: Clone the Repository

Start by cloning the official Langfuse repository to access the Docker configuration and environment templates:

git clone https://github.com/langfuse/langfuse.git
cd langfuse

The repository contains the docker-compose.yml file that orchestrates all services, along with example environment files in the root directory.

Step 2: Configure Environment Variables

Langfuse requires a .env file for configuration. Copy the development example and customize it for your deployment:

cp .env.dev.example .env

Open .env in your editor and replace all placeholder values marked with # CHANGEME. The critical variables requiring secure values are:

Variable	Purpose	Generation Command
ENCRYPTION_KEY	Encrypts sensitive data at rest	openssl rand -hex 32
NEXTAUTH_SECRET	Secures authentication sessions	openssl rand -hex 32
SALT	Additional entropy for hashing	openssl rand -hex 32

The .env.dev.example file includes comments explaining each variable. For production deployments, also configure LANGFUSE_INIT_* variables to create an initial admin user automatically.

Step 3: Launch the Docker Compose Stack

With your .env file configured, start all services with a single command:

docker compose up

Add the -d flag to run in detached (background) mode:

docker compose up -d

Docker Compose will pull images for all services and start them in dependency order. The first startup typically takes 2–5 minutes as images download and databases initialize.

Step 4: Access the Langfuse Web Interface

Once the stack is running, open your browser to:

http://localhost:3000

The web interface (langfuse-web container) serves the Next.js application on port 3000. If you configured LANGFUSE_INIT_USERNAME and LANGFUSE_INIT_PASSWORD in your .env file, use those credentials to log in. Otherwise, follow the first-run prompts to create an admin account.

---

Understanding the Docker Compose Architecture

The docker-compose.yml file in the repository root defines seven interconnected containers. Understanding this architecture helps with troubleshooting and scaling decisions.

Core Service Containers

Container	Image	Role	Source File
langfuse-web	langfuse/langfuse	Next.js UI and API gateway	web/Dockerfile
langfuse-worker	langfuse/langfuse-worker	Background job processor	worker/Dockerfile
postgres	postgres:16	Relational database for metadata	docker-compose.yml
clickhouse	clickhouse/clickhouse-server	Column-store for trace events	docker-compose.yml
redis	redis:7	Queue broker and cache	docker-compose.yml
minio	minio/minio	S3-compatible object storage	docker-compose.yml

Data Persistence

Docker Compose configures named volumes for all stateful services:

• langfuse_postgres_data — PostgreSQL tables and indexes
• langfuse_clickhouse_data — Columnar trace data
• langfuse_redis_data — Queue state and cache
• minio_data — S3 objects and exports

These volumes persist across container restarts. To completely reset the installation, run docker compose down -v to remove volumes, then docker compose up to recreate them.

---

Local Development Installation (Optional)

For contributors modifying the Langfuse source code, the repository supports a local development environment using pnpm workspaces.

Install Development Dependencies

pnpm install

This command reads pnpm-workspace.yaml and installs dependencies for all packages in the monorepo, including the web and worker applications.

Start Development Servers

Run the web UI with hot reload:

pnpm run dev:web

Run the background worker in watch mode:

pnpm run dev:worker

The development setup requires the same backing services (PostgreSQL, ClickHouse, Redis, MinIO) running via Docker Compose. You can start just the infrastructure services with:

docker compose up postgres clickhouse redis minio

See CONTRIBUTING.md for additional development guidelines and the agents:check workflow for automated validation.

---

Troubleshooting Common Installation Issues

Port Conflicts

If port 3000 is already in use, modify the PORT environment variable in .env and update the port mapping in docker-compose.yml:

ports:
  - "${PORT:-3000}:3000"

Database Connection Failures

The langfuse-web and langfuse-worker containers fail if databases are not ready. Docker Compose includes depends_on with health checks, but on slow systems you may need to increase startup delays:

docker compose up --wait

Missing Environment Variables

The application logs detailed errors for missing required variables. Check container logs with:

docker compose logs langfuse-web

Ensure all # CHANGEME placeholders in .env are replaced with actual values.

---

Summary

• Langfuse installs via Docker Compose — a single docker compose up command launches the complete stack including PostgreSQL, ClickHouse, Redis, MinIO, web UI, and worker.
• Configuration lives in .env — copy .env.dev.example to .env and generate secure keys with openssl rand -hex 32 for ENCRYPTION_KEY, NEXTAUTH_SECRET, and SALT.
• Access the UI at localhost:3000 — the web container exposes this port by default; first-run setup creates your admin account.
• Data persists in Docker volumes — named volumes for each service keep state across restarts; use docker compose down -v to reset completely.
• Development setup uses pnpm — run pnpm install and pnpm run dev:web / pnpm run dev:worker for local code contributions.

---

Frequently Asked Questions

What are the minimum system requirements for self-hosting Langfuse?

Self-hosted Langfuse requires approximately 4–6 GB of RAM for all services to run comfortably. A modern multi-core CPU is recommended for the ClickHouse and PostgreSQL containers. Docker Desktop or a Linux Docker environment with compose support is mandatory. For production workloads, allocate additional disk space for the named volumes and consider running databases on dedicated infrastructure.

Can I use an external PostgreSQL or ClickHouse database instead of the Docker containers?

Yes. The docker-compose.yml file defines services with standard connection environment variables. To use external databases, remove the postgres or clickhouse service from your compose file and set the corresponding connection strings in .env (e.g., DATABASE_URL for PostgreSQL, CLICKHOUSE_URL for ClickHouse). Ensure network connectivity and proper authentication for the external services.

How do I upgrade to a new version of Langfuse?

To upgrade, pull the latest images and restart the stack. Run docker compose pull to fetch updated langfuse/langfuse and langfuse/langfuse-worker images, then docker compose up -d to recreate containers with the new versions. Database migrations run automatically on startup. Review the release notes for any breaking changes to environment variables or required manual steps before upgrading production instances.

Is there a way to install Langfuse without Docker?

Docker is the officially supported installation method for self-hosting. The production containers defined in web/Dockerfile and worker/Dockerfile handle complex build steps including Next.js compilation and Prisma client generation. While advanced users could manually replicate these steps on a Node.js host, this approach is not documented or supported. For non-Docker deployments, use Langfuse Cloud or container orchestration platforms like Kubernetes that can run the official images.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}