Docker Compose

Get LangWatch running locally in minutes with Docker Compose

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

LangWatch is available at http://localhost:5560.

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

See Environment Variables for the full reference.

Common Operations

Start in the background

docker compose up -d

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f app

Stop services

docker compose down

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:
  #   ...

Remove the corresponding upstream URLs from the app environment to avoid connection errors.

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

• Docker Images — Learn about each container image
• Kubernetes (Helm) — Production deployment
• Environment Variables — Full configuration reference