Docker Compose Reference

Canonical source: docs/08-runtime-devops/docker-compose-reference.md — this page is rendered from it on every publish; edit the source.

Docker Compose Reference

Every compose file, its purpose, and when to use it.

---

1. Compose File Inventory

The compose configuration is split by layer and environment. There is no single all-in-one compose file; ./scripts/claw.sh is the only supported way to bring the stack up, because it stitches the right files together and auto-applies the GPU overlay:

File	Purpose	Usage
docker/docker-compose.dev.databases.yml	Dev databases + infrastructure (PostgreSQL per service, MongoDB, Redis, RabbitMQ, ClamAV)	claw.sh (dev)
docker/docker-compose.dev.services.yml	Dev backend services + nginx + frontend	claw.sh (dev)
docker/docker-compose.dev.ollama.yml	Dev local-AI runtime (Ollama and friends)	claw.sh --local-ai
docker/docker-compose.prod.databases.yml	Prod databases + infrastructure	claw.sh --prod
docker/docker-compose.prod.services.yml	Prod backend services + nginx + frontend	claw.sh --prod
docker/docker-compose.prod.ollama.yml	Prod local-AI runtime	claw.sh --prod --local-ai
docker/docker-compose.{dev,prod}.gpu-{nvidia,rocm,vulkan}.yml, docker/docker-compose.{dev,prod}.ollama.gpu-nvidia.yml	GPU overlays	auto-applied by claw.sh
docker/docker-compose.feedback-e2e.yml	Feedback end-to-end test stack	test lane only

Layers

claw.sh starts and stops each layer independently:

./scripts/claw.sh up        # Starts all layers in order
./scripts/claw.sh status    # Shows status of all layers

---

2. Service Definitions

Infrastructure Services

All compose files define the same infrastructure services:

Service	Image	Port Mapping	Volume	Health Check
pg-auth	pgvector/pgvector:pg16	5441:5432	pg-auth-data	pg_isready (10s interval)
pg-chat	pgvector/pgvector:pg16	5442:5432	pg-chat-data	pg_isready
pg-connector	pgvector/pgvector:pg16	5443:5432	pg-connector-data	pg_isready
pg-routing	pgvector/pgvector:pg16	5444:5432	pg-routing-data	pg_isready
pg-memory	pgvector/pgvector:pg16	5445:5432	pg-memory-data	pg_isready
pg-files	pgvector/pgvector:pg16	5446:5432	pg-files-data	pg_isready
pg-ollama	pgvector/pgvector:pg16	5447:5432	pg-ollama-data	pg_isready
pg-images	pgvector/pgvector:pg16	5448:5432	pg-images-data	pg_isready
pg-file-generations	pgvector/pgvector:pg16	5449:5432	pg-file-gen-data	pg_isready
mongodb	mongo:7	27018:27017	mongo-data	mongosh --eval "db.runCommand('ping')"
redis	redis:7-alpine	6380:6379	redis-data	redis-cli ping
rabbitmq	rabbitmq:3-management-alpine	5672,15672	rabbitmq-data	rabbitmq-diagnostics check_running

Backend Services

Service	Dockerfile	Port	Depends On
auth-service	Dockerfile.dev	4001	pg-auth, redis, rabbitmq
chat-service	Dockerfile.dev	4002	pg-chat, redis, rabbitmq
connector-service	Dockerfile.dev	4003	pg-connector, redis, rabbitmq
routing-service	Dockerfile.dev	4004	pg-routing, redis, rabbitmq
memory-service	Dockerfile.dev	4005	pg-memory, redis, rabbitmq
file-service	Dockerfile.dev	4006	pg-files, redis, rabbitmq
audit-service	Dockerfile.dev	4007	mongodb, redis, rabbitmq
ollama-service	Dockerfile.dev	4008	pg-ollama, redis, rabbitmq
health-service	Dockerfile.dev	4009	redis, rabbitmq
client-logs-service	Dockerfile.dev	4010	mongodb, redis, rabbitmq
server-logs-service	Dockerfile.dev	4011	mongodb, redis, rabbitmq
image-service	Dockerfile.dev	4012	pg-images, redis, rabbitmq
file-generation-service	Dockerfile.dev	4013	pg-file-generations, redis, rabbitmq

Proxy and Frontend

Service	Image/Build	Port	Depends On
nginx	nginx:alpine	4000	All backend services (healthy)
frontend	Custom (Next.js)	3000	nginx (service_started)

---

3. Network Configuration

All containers connect to a single bridge network:

networks:
  claw-network:
    driver: bridge

Services communicate using Docker DNS hostnames that match the service name. The nginx resolver uses Docker's internal DNS (127.0.0.11) with 5-second TTL.

---

4. Volume Definitions

Named Volumes (14 total)

volumes:
  pg-auth-data:
  pg-chat-data:
  pg-connector-data:
  pg-routing-data:
  pg-memory-data:
  pg-files-data:
  pg-ollama-data:
  pg-images-data:
  pg-file-generations-data:
  mongo-data:
  redis-data:
  rabbitmq-data:
  ollama-data:
  file-storage-data:

Host Mounts (Dev Only)

Backend services mount source code for hot reload:

volumes:
  - ./apps/claw-auth-service/src:/app/apps/claw-auth-service/src
  - ./apps/claw-auth-service/prisma:/app/apps/claw-auth-service/prisma

Frontend mounts source and public:

volumes:
  - ./apps/claw-frontend/src:/app/src
  - ./apps/claw-frontend/public:/app/public

Nginx config is mounted read-only:

volumes:
  - ./infra/nginx/nginx.conf:/etc/nginx/nginx.conf:ro

---

5. Environment Variables

All services use env_file: .env from the repository root. The single .env file contains all configuration for all services.

Database container environment variables use interpolation:

environment:
  POSTGRES_USER: ${PG_AUTH_USER}
  POSTGRES_PASSWORD: ${PG_AUTH_PASSWORD}
  POSTGRES_DB: ${PG_AUTH_DB}

---

6. Health Check Configuration

Database Health Checks

healthcheck:
  test: ['CMD-SHELL', 'pg_isready -U ${PG_AUTH_USER} -d ${PG_AUTH_DB}']
  interval: 10s
  timeout: 5s
  retries: 5

Backend Service Health Checks

healthcheck:
  test: ['CMD', 'wget', '-qO-', 'http://localhost:4001/api/v1/health']
  interval: 15s
  timeout: 10s
  retries: 10
  start_period: 45s

Startup Order

Dependencies use condition: service_healthy to ensure correct startup order:

Layer 1: All databases, Redis, RabbitMQ, Ollama (no dependencies)
Layer 2: All backend services (depend on their database + redis + rabbitmq)
Layer 3: Nginx (depends on all backend services being healthy)
Layer 4: Frontend (depends on nginx being started)

---

7. Dev vs Prod Differences

Aspect	Development	Production
Dockerfile	Dockerfile.dev	Dockerfile
Hot reload	Source mounted, node --watch	Built image, no mounts
Build target	Dev dependencies included	Only production deps
Next.js	Turbopack dev server	Optimized production build
Source maps	Enabled	Disabled
Port exposure	All ports exposed to host	Only nginx (4000) exposed
Restart policy	restart: unless-stopped	restart: always

---

8. Common Operations

# Start everything (dev)
./scripts/claw.sh up -d

# Stop everything
./scripts/claw.sh down

# Stop and delete all data
./scripts/claw.sh down -v

# Restart a single service
./scripts/claw.sh restart chat-service

# Rebuild and restart a single service
./scripts/claw.sh service:rebuild chat-service

# View logs
./scripts/claw.sh logs -f chat-service

# Check status
./scripts/claw.sh ps

# Start with management script
./scripts/claw.sh up
./scripts/claw.sh status
./scripts/claw.sh down