Post

Langfuse Self-Hosting Startup Guide (Local Deployment)

Langfuse Self-Hosting Startup Guide (Local Deployment)

Easily deploy Langfuse locally with Docker, configure users and projects, and connect via the SDK.


πŸš€ Step 1: Clone the Langfuse Repository

Start by cloning the Langfuse GitHub repository:

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

βš™οΈ Step 2: Create and Configure the .env File

Langfuse requires a .env file in the root directory for configuration.

Copy the content of file .env.prod.example in the project to a .env file

πŸ”Έ OR πŸ”Ή

πŸ“ Create a .env file: with the below

Add the following content (customized for your setup) to .env

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
# --- PostgreSQL Database Configuration ---
DATABASE_URL="postgresql://postgres:postgres@db:5432/postgres"

# --- Application URLs ---
NEXTAUTH_URL="http://localhost:3000"

# --- Secrets and Security ---
NEXTAUTH_SECRET="X2v42emRGCtcYobj3ZWwTJkLIOHkUuxl1bLcZkuEG20="
SALT="salt"
ENCRYPTION_KEY="0000000000000000000000000000000000000000000000000000000000000000"

# --- OpenTelemetry (Optional Observability) ---
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
OTEL_SERVICE_NAME="langfuse"

# --- Default Resource Provisioning (Automated Setup) ---
LANGFUSE_INIT_ORG_ID=org-id
LANGFUSE_INIT_ORG_NAME=org-name
LANGFUSE_INIT_PROJECT_ID=project-id
LANGFUSE_INIT_PROJECT_NAME=project-name
LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-1234567890
LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-1234567890
LANGFUSE_INIT_USER_EMAIL=user@example.com
LANGFUSE_INIT_USER_NAME=abhishek
LANGFUSE_INIT_USER_PASSWORD=password@1234

βœ… This automates the setup of your default organization, project, and admin user.

You may also copy content from .env.prod.example as a reference and adjust as needed.


🐳 Step 3: Start Langfuse with Docker

Ensure Docker and Docker Compose are installed.

🧱 Run services using Docker Compose:

1
docker-compose up -d --build

IT should run the docker-compose.yml file in the project

This starts the entire Langfuse stack, including the database.


🌐 Step 4: Access the Langfuse Dashboard

Once Docker is running:

πŸ”— Visit: http://localhost:3000

πŸ” Login credentials:

  • Email: user@example.com
  • Password: password@1234

Set via .env using LANGFUSE_INIT_USER_* variables.


πŸ“¦ Services Started by Docker Compose

The docker-compose.yml starts the following services:

ServiceDescription
langfuseMain Langfuse application
dbPostgreSQL database
clickhouse(Optional) Analytics storage
otelOpenTelemetry collector (opt.)

πŸ‘‰ Make sure the .env matches the same values for db and services.


🧠 Step 5: Use Langfuse SDK (Optional)

Once running, you can connect your app to Langfuse via SDK.

πŸ§ͺ Export SDK keys in your terminal session:

1
2
3
export LANGFUSE_PUBLIC_KEY=pk-1234567890
export LANGFUSE_SECRET_KEY=sk-1234567890
export LANGFUSE_HOST=http://localhost:3000

Replace values if you use different ones in your .env.

This allows the Langfuse SDK (in Python, Node, etc.) to authenticate and send traces to your local Langfuse instance.


🧩 Tips

To regenerate secrets, use:

1
2
openssl rand -base64 32    # For NEXTAUTH_SECRET
openssl rand -hex 32       # For ENCRYPTION_KEY
  • You can customize services or add extras like Redis or S3 later.
  • All default resources (org, project, user) are automatically created via the LANGFUSE_INIT_* variables on first run.

How to Verify All Components Are Running Properly

Your self-hosted Langfuse consists of several interconnected services:

  • langfuse-web (frontend/API)
  • langfuse-worker (event ingestion/background processing)
  • PostgreSQL (primary transactional store)
  • ClickHouse (analytics/OLAP store)
  • Redis (queue & cache)
  • MinIO or S3 (object/event storage)

Steps to Check Service Health

A. Health & Readiness Endpoints

Langfuse provides built-in HTTP endpoints for basic health checks:

Frontend (langfuse-web):

1
2
curl http://localhost:3000/api/public/health
curl http://localhost:3000/api/public/ready
  • 200 OK β†’ healthy and connected to DB.
  • 503 β†’ unhealthy, e.g. DB not connected.

Optionally add ?failIfDatabaseUnavailable=true to include DB connectivity in the check.


Worker (langfuse-worker):

1
curl http://localhost:3030/api/health
  • Returns 200 OK if the worker can access its dependencies successfully.

These are ideal for monitoring tools (e.g., Prometheus, uptime checks).
Note: Cloud setup may use an extended flag like failIfNoRecentEvents, but this isn’t default for self-hosted.


B. Inspect Docker Container Status

Use Docker commands to ensure all services are up:

1
2
docker ps
docker-compose logs -f

Look for:

  • Containers running without restarts
  • No crashes or repeated failures in logs

C. Confirm Each Component’s Connectivity

PostgreSQL:
Try connecting inside the container:

1
docker exec -it <postgres_container> psql -U <user> -d <db>

Check tables and schema.


ClickHouse:
Similar approach; you can use curl to test TCP (9000) or HTTP (8123) endpoints.


Redis:
Use a Redis client:

1
redis-cli ping

Or check keys.


MinIO / S3:

This post is licensed under CC BY 4.0 by the author.