Docker Compose is the quickest way to try LangWatch locally. It runs the full stack in containers on your machine.
Prerequisites
- Docker with Docker Compose v2
- 4 CPU cores, 8 GB RAM, 20 GB disk
Quick Start
# Clone the repository
git clone https://github.com/langwatch/langwatch.git
cd langwatch
# Copy the example environment file
cp langwatch/.env.example langwatch/.env
# Start all services
docker compose up
Why port 5560? On a T9 keyboard, 5560 spells “LLM”.
Services
Docker Compose starts the following services:
| Service | Image | Port | Description |
|---|
app | langwatch/langwatch:latest | 5560 | Main application |
workers | langwatch/langwatch:latest | — | Background job processing |
langwatch_nlp | langwatch/langwatch_nlp:latest | 5561 | NLP processing, workflows |
langevals | langwatch/langevals:latest | 5562 | Evaluators, guardrails |
postgres | postgres:16 | 5432 | Control plane database |
redis | redis:alpine | — | Job queue, caching |
clickhouse | langwatch/clickhouse-serverless:0.2.0 | 8123 | Trace and analytics storage |
Configuration
Edit langwatch/.env to customize your deployment. Key variables:
# Required: generate a secret for each
API_TOKEN_JWT_SECRET=your-jwt-secret
CREDENTIALS_SECRET=your-encryption-key
NEXTAUTH_SECRET=your-session-secret
Common Operations
Start in the background
View logs
# All services
docker compose logs -f
# Specific service
docker compose logs -f app
Stop services
Update to latest version
docker compose pull
docker compose up -d
Reset data
docker compose down -v # Removes volumes (all data)
docker compose up
Customization
Disable optional services
If you don’t need NLP or evaluators, comment them out in compose.yml:
services:
# langwatch_nlp:
# ...
# langevals:
# ...
Connect to external databases
Replace the postgres and redis services with connection strings to your existing instances:
services:
app:
environment:
DATABASE_URL: postgresql://user:password@your-postgres:5432/langwatch
REDIS_URL: redis://:password@your-redis:6379
depends_on: [] # Remove postgres and redis dependencies
Connect to external ClickHouse
Replace the clickhouse service with a connection string to your existing instance:
services:
app:
environment:
CLICKHOUSE_URL: http://user:password@your-clickhouse:8123/langwatch
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
# Remove clickhouse from depends_on
Limitations
Docker Compose is suitable for evaluation and small teams but lacks:
- High availability — single instance of each service
- Horizontal scaling — cannot scale workers independently
- Automated backups — no built-in backup scheduling
- TLS — no built-in HTTPS (use a reverse proxy like nginx or Caddy)
For production, migrate to the Kubernetes Helm chart.
Next Steps
