> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.docker.com/get-docker/) with Docker Compose v2
* 4 CPU cores, 8 GB RAM, 20 GB disk

## Quick Start

```bash theme={null}
# 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](http://localhost:5560)**.

<Tip>
  Why port 5560? On a T9 keyboard, 5560 spells "LLM".
</Tip>

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

```bash theme={null}
# 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](/self-hosting/configuration/environment-variables) for the full reference.

## Common Operations

### Start in the background

```bash theme={null}
docker compose up -d
```

### View logs

```bash theme={null}
# All services
docker compose logs -f

# Specific service
docker compose logs -f app
```

### Stop services

```bash theme={null}
docker compose down
```

### Update to latest version

```bash theme={null}
docker compose pull
docker compose up -d
```

### Reset data

```bash theme={null}
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`:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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](/self-hosting/deployment/kubernetes-helm).

## Next Steps

* [Docker Images](/self-hosting/deployment/docker-images) — Learn about each container image
* [Kubernetes (Helm)](/self-hosting/deployment/kubernetes-helm) — Production deployment
* [Environment Variables](/self-hosting/configuration/environment-variables) — Full configuration reference