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, then replace its placeholder secrets (see Configuration)
cp .env.example .env

# Start all services
docker compose -f infra/compose.yml --project-directory . up

The compose file lives at infra/compose.yml and reads .env at the repository root, so run every docker compose command from the repository root with -f infra/compose.yml --project-directory .. The commands below use that form.

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	Host port	Description
app	langwatch/langwatch:latest	5560	Main application
workers	langwatch/langwatch:latest	-	Background job processing
langwatch_nlp	langwatch/langwatch_nlp:latest	-	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

Services with no host port bind no port on the host’s interfaces, so they do not answer on localhost and are not reachable from another machine. langwatch_nlp listens on 5561 inside the Docker network, which is what LANGWATCH_NLP_SERVICE points the app and the workers at. A process on the Docker host itself can still reach a container directly on its own network address, so treat this as removing an exposed entry point, not as a network boundary.

Configuration

Edit .env to customize your deployment. Key variables:

# Required: replace the placeholders that .env.example ships
# Signs sessions. Generate with: openssl rand -base64 32
NEXTAUTH_SECRET=your-session-secret
# Encrypts stored credentials and peppers API key hashes.
# Must be exactly 64 hex characters. Generate with: openssl rand -hex 32
CREDENTIALS_SECRET=your-64-hex-character-key

# Optional: shared credential the app authenticates to the NLP service with.
# Every container in the stack reads this file, so one value covers both sides.
# Generate with: openssl rand -hex 32
LANGWATCH_NLP_INTERNAL_SECRET=

# Optional: an Enterprise license, either an activation code
# (LW-XXXX-XXXX-XXXX-XXXX, needs outbound HTTPS to connect.langwatch.ai)
# or a signed license key (works offline)
LANGWATCH_LICENSE_KEY=

See Editions and licensing for how each form is applied at startup. Keep CREDENTIALS_SECRET stable once LangWatch holds data: changing it makes stored credentials unreadable and invalidates API keys. To replace it, see Rotating the credentials secret. See Environment Variables for the full reference.

Common Operations

Start in the background

docker compose -f infra/compose.yml --project-directory . up -d

View logs

# All services
docker compose -f infra/compose.yml --project-directory . logs -f

# Specific service
docker compose -f infra/compose.yml --project-directory . logs -f app

Stop services

docker compose -f infra/compose.yml --project-directory . down

Update to latest version

docker compose -f infra/compose.yml --project-directory . pull
docker compose -f infra/compose.yml --project-directory . up -d

The workers run pnpm task upgrade on the new image when they start, and the app does not report ready until it completes. On a current installation it applies no step. If it fails, read docker compose logs workers; the exit code is explained in the Upgrade Guide.

Reset data

docker compose -f infra/compose.yml --project-directory . down -v  # Removes volumes (all data)
docker compose -f infra/compose.yml --project-directory . up

Customization

Disable optional services

If you don’t need NLP or evaluators, comment them out in infra/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

• First run: Create the first account, add the license and connect your identity provider
• Docker Images: Learn about each container image
• Kubernetes (Helm): Production deployment
• Environment Variables: Full configuration reference