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

# Docker Setup

> Run Agent Diff locally with Docker

## Quick Start

The simplest way to run Agent Diff:

```bash theme={null}
git clone https://github.com/hubertpysklo/agent-diff.git
cd agent-diff/ops
docker-compose up
```

<Check>
  Backend running at `http://localhost:8000`
</Check>

This starts:

* PostgreSQL database (with logical replication enabled)
* Agent Diff backend
* Auto-seeded templates (Slack, Linear)

## Makefile Commands

```bash theme={null}
cd ops

# Start services (local PostgreSQL)
make up

# Stop services
make down

# View logs
make logs

# Run tests
make test

# Run seed scripts
make seed

# Create a new Alembic migration
make create-migration MESSAGE="add column"
```

## Using External Database (Neon)

If you want to use an external PostgreSQL like Neon:

```bash theme={null}
# Create .env file
echo 'DATABASE_URL=postgresql://user:pass@host/db' > .env

# Start with external profile
make up-external
```

Or with docker-compose directly:

```bash theme={null}
DATABASE_URL=postgresql://user:pass@host/db \
  docker-compose --profile external up -d backend-external
```

## Environment Variables

| Variable                      | Default                            | Description                  |
| ----------------------------- | ---------------------------------- | ---------------------------- |
| `DATABASE_URL`                | Local postgres                     | PostgreSQL connection string |
| `LOGICAL_REPLICATION_ENABLED` | `true`                             | Enable diff capture via WAL  |
| `SEED`                        | `true` (local), `false` (external) | Run seed scripts on startup  |
| `ENVIRONMENT`                 | `development`                      | Environment name             |

### Optional Performance Tuning

| Variable                     | Default | Description                        |
| ---------------------------- | ------- | ---------------------------------- |
| `MAINTENANCE_IDLE_TIMEOUT`   | `300`   | Seconds before pool refill stops   |
| `MAINTENANCE_CYCLE_INTERVAL` | `10`    | Seconds between maintenance cycles |
| `POOL_REFILL_CONCURRENCY`    | `10`    | Parallel schema builds             |
| `REPLICATION_IDLE_TIMEOUT`   | `300`   | Seconds before replication stops   |

## Docker Compose Structure

```yaml theme={null}
services:
  postgres:
    image: postgres:16-alpine
    command: >
      postgres -c wal_level=logical 
               -c max_replication_slots=10 
               -c max_wal_senders=10
    # Required for logical replication (diff capture)

  backend:
    build: ../backend
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ../backend:/app      # Live code reload
      - ../examples:/examples # Seed data
      - ../sdk:/sdk          # SDK access
```

## Volumes

The Docker setup uses a named volume for PostgreSQL data:

```yaml theme={null}
volumes:
  postgres_data:
```

To reset the database:

```bash theme={null}
docker-compose down -v
docker-compose up
```

## Health Check

```bash theme={null}
curl http://localhost:8000/api/platform/health
```

```json theme={null}
{
  "status": "healthy",
  "service": "agent-diff"
}
```

## Logs

View backend logs:

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

# Backend only
docker-compose logs -f backend

# PostgreSQL only
docker-compose logs -f postgres
```

## Common Issues

### Port Already in Use

```bash theme={null}
# Check what's using port 8000
lsof -i :8000

# Use a different port
PORT=8001 docker-compose up
```

### Database Connection Errors

```bash theme={null}
# Reset the database
docker-compose down -v
docker-compose up
```

### Seed Data Not Loading

```bash theme={null}
# Force re-seed
SEED=true docker-compose up --force-recreate backend
```

## Development Mode

For development with live reload:

```bash theme={null}
# The default docker-compose.yml mounts your local code
docker-compose up

# Changes to backend/ are reflected immediately
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/hosting/configuration">
    Advanced configuration options
  </Card>

  <Card title="Neon Setup" icon="database" href="/hosting/neon-setup">
    Use serverless PostgreSQL
  </Card>
</CardGroup>