Self-hosting

Muster ships as a Docker Compose stack. The bundled docker-compose.yml brings up six services: the web app, a background worker, Postgres, ClickHouse, Redis, and MinIO (an S3-compatible blob store).

This guide is the shortest path from a fresh server to a working install. Production-grade deployments (managed Postgres, real S3, TLS, secrets in a vault) are out of scope here — wire those in once the basic stack is healthy.

Prerequisites

Docker Engine 24.0+ and Docker Compose v2
4 vCPU and 8 GB RAM (minimum; more for production traffic)
50 GB free disk for Postgres + ClickHouse + MinIO
A free TCP port for the web app (default 3000)
openssl available locally to generate secrets

Essential environment variables

Copy .env.prod.example to .env and fill in at least these:

Variable	Purpose
`DATABASE_URL`	Postgres connection string for users, projects, configs
`NEXTAUTH_SECRET`	Session-cookie signing key. Generate: `openssl rand -hex 32`
`SALT`	API-key hashing salt. Generate: `openssl rand -hex 32`
`ENCRYPTION_KEY`	256-bit at-rest encryption key. Generate: `openssl rand -hex 32`
`CLICKHOUSE_URL`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`	ClickHouse connection
`REDIS_HOST`, `REDIS_AUTH`	Redis for queues and cache
`LANGFUSE_S3_EVENT_UPLOAD_BUCKET`	Bucket name for ingestion event blobs (required)

If you also want emails (invitations, password reset, weekly reports), set:

EMAIL_FROM_ADDRESS
SMTP_CONNECTION_URL

If you're rebranding, set the four MUSTER_* vars described in the branding env vars:

MUSTER_DOCS_URL
MUSTER_WEBSITE_URL
MUSTER_CONTACT_EMAIL
MUSTER_BRAND_NAME

These flip every "Learn more" link, mailto, and brand mention in the UI to your values.

Spin it up

# 1. Configuration
cp .env.prod.example .env
# Edit .env — at minimum set the secrets above with real values

# 2. Bring up the stack
docker compose up -d

# 3. Create the MinIO buckets the first time
docker exec muster-minio mc alias set local http://localhost:9000 minioadmin minioadmin
docker exec muster-minio mc mb local/muster-events --ignore-existing
docker exec muster-minio mc mb local/muster-media  --ignore-existing

Database migrations run automatically on first boot. The web container won't finish starting until ClickHouse and Postgres are reachable, so the first boot can take a minute or two.

Verify it's healthy

# All services should show "running"
docker compose ps

# Web responds
curl -fsS http://localhost:3000/api/public/health
# Expected: 200 OK

# Migrations ran
docker compose logs muster-web | grep -i migration

# Worker is processing
docker compose logs muster-worker --tail 20

Open http://localhost:3000, sign up the first admin user, and create a project. Then follow Get Started to send your first trace.

Common issues

Web container restarts on boot. Almost always Postgres or ClickHouse isn't reachable. Check docker compose logs muster-web for the exact connection error.

Traces don't appear in the UI. The worker container is the ingestion path. If docker compose logs muster-worker shows it crashed or never started, traces queue up but never persist.

Failed to connect to S3 on first ingestion. You forgot to create the event-upload bucket. Run the mc mb command from the spin-it-up section.

ENCRYPTION_KEY must be 256 bits on boot. The key has to be exactly 64 hex characters. Re-generate with openssl rand -hex 32 (not base64).

What's next

Once the stack is healthy, the next config touchpoints are usually:

SSO providers (Google, GitHub, Okta, Azure AD, etc.) — see the AUTH_* block in .env.prod.example
Real S3 instead of MinIO — point LANGFUSE_S3_* at your bucket
A managed Postgres — replace DATABASE_URL with the managed connection string
Email — set SMTP_CONNECTION_URL