Docker Dev

Docker Development Environment Manager

Manage the Docker Compose dev stack and the Jinja2 template generation system. The action is passed via $ARGUMENTS.

Documentation Lookup

For Docker Compose or Traefik questions, use Context7 MCP to fetch up-to-date docs:

• Docker Compose: mcp__context7__resolve-library-id with query docker compose, then mcp__context7__query-docs with library ID /docker/compose
• Traefik: mcp__context7__resolve-library-id with query traefik, then mcp__context7__query-docs with library ID /websites/doc_traefik_io_traefik

Day-to-Day Actions

up — Start the development stack

docker compose -f infra/docker-compose.dev.yml --env-file .env up -d --build

Pre-check: Verify .env exists at the repo root. If missing, copy from .env.dev:

cp .env.dev .env

down — Stop the development stack

docker compose -f infra/docker-compose.dev.yml down

health — Check all service health statuses

1. Run docker compose -f infra/docker-compose.dev.yml ps --format json
2. For each service, report: name, status, health, exposed ports
3. Test connectivity to key endpoints with curl -s -o /dev/null -w "%{http_code}":
   • API: http://localhost:8000
   • OpenWebUI: http://localhost:8080
   • Langfuse: http://localhost:6006
   • LiteLLM: http://localhost:4000
   • Dagster: http://localhost:3000
   • SeaweedFS: http://localhost:8889
   • NATS: http://localhost:8222

logs <service> — Tail logs for a specific service

docker compose -f infra/docker-compose.dev.yml logs --tail 100 -f <service>

restart <service> — Restart a specific service

docker compose -f infra/docker-compose.dev.yml restart <service>

status — Show running containers with resource usage

docker compose -f infra/docker-compose.dev.yml ps
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

ports — Show all exposed service URLs

Note: API (:8000), Admin UI (:3333), and Dagster (:3000) run locally outside Docker in dev — they're not in infra/docker-compose.dev.yml.

generate — Regenerate compose files from templates

make generate-compose

Run this after editing any template in infra/deployment/templates/ or infra/deployment/compose-config.yml. Commit both the template changes and the regenerated output files.

Compose Generation System

Read infra/deployment/CLAUDE.md for full details. Quick overview:

Architecture: A single Jinja2 template (infra/deployment/templates/docker-compose.yml.j2) + a single config file (infra/deployment/compose-config.yml) produce 10 docker-compose variants (5 stages x 2 GPU modes).

Key files:

• infra/deployment/compose-config.yml — image tags + stage-specific values (SINGLE SOURCE OF TRUTH)
• infra/deployment/generate_compose.py — Jinja2 renderer
• infra/deployment/templates/docker-compose.yml.j2 — main template (~3000 lines)
• infra/deployment/templates/configs/ — 15 service config templates (NATS, LiteLLM, Traefik, Milvus, etc.)

5 Stages:

Each stage has a .gpu variant adding NVIDIA GPU support.

Generated outputs (under infra/ — NEVER edit directly):

• infra/docker-compose.{stage}{.gpu}.yml — 10 compose files
• infra/configs/{service}/{config} — ~80 service config files

Workflow for template changes: Edit template → make generate-compose → commit templates + generated files.

Network Zones

5 isolated Docker networks (see docs/arc42/decisions/2025_12_22_docker_network_isolation.md):

Dev stage has all networks non-internal for localhost access.

Examples

• /docker-dev up — Start all services
• /docker-dev down — Stop all services
• /docker-dev health — Check which services are running and healthy
• /docker-dev logs nats — Tail NATS logs
• /docker-dev restart litellm — Restart LiteLLM proxy
• /docker-dev status — Show containers and resource usage
• /docker-dev ports — List all service URLs
• /docker-dev generate — Regenerate compose files from templates

Troubleshooting

Source: bbvch-ai/aihub-core — distributed by TomeVault.