docker-compose-operations
Operations for local container stacks defined in docker-compose.yaml or docker-compose/ directory. Handles AI/ML services (Ollama, ComfyUI), standalone databases, and local observability stacks. Use f
SKILL.md.claude/skills/docker-compose-operations/SKILL.md
GitHub- Access services via
*.127.0.0.1.nip.iodomains through Envoy gateway - GPU services require
runtime: nvidia(NVIDIA Docker runtime) - Use
docker compose logs -f <service>for real-time log monitoring - Inside the claudex sandbox every
dockersubcommand reaches the rootless daemon, which holds none of this stack - take the route in### Reaching the Stack from the claudex Sandboxinstead
Service Categories
| Category | Services | Access |
|---|---|---|
| AI/ML (profile) | comfyui, stable-diffusion-*, llama.cpp, yue | Profile-based |
| AI/ML (always-on) | ollama, open-webui | Always-on |
| Web | pianify | Always-on |
| Observability | grafana, prometheus, tempo, loki, opentelemetry-collector, pyroscope | Always-on |
| Datastores | mysql, redis, minio, qdrant, cassandra, influxdb | Always-on |
| Gateway | envoy, mitmproxy | Always-on |
| MCP Servers | github-mcp-server, playwright-mcp, chrome-devtools-mcp, mcp-filesystem | Always-on |
Available Profiles
| Profile | Description | GPU |
|---|---|---|
| stable-diffusion-webui | Original Stable Diffusion WebUI | Yes |
| stable-diffusion-webui-forge | Improved Stable Diffusion WebUI | Yes |
| comfyui | Node-based AI image generation | Yes |
| llama.cpp | LLaMA.cpp for LLM inference | Yes |
| yue | Yue server | Yes |
Common Commands
# Start profile-based services
docker compose --profile=comfyui up -d
# View logs
docker compose logs -f grafana
# Execute commands in container
docker compose exec redis redis-cli
docker compose exec mysql mysql -u hippocampus -p
# Check GPU status
docker compose exec dcgm-exporter nvidia-smi
# Restart service
docker compose restart prometheus
Web Interfaces
Services are accessible via http://{service}.127.0.0.1.nip.io.
See docker-compose/envoy/envoy.yaml for available domains.
| Service | URL | Note |
|---|---|---|
| Envoy Admin | http://localhost:9901 |
Direct access |
| mitmproxy Web | http://localhost:18081 |
Open the ?token= URL mitmweb prints on each start in journalctl -u hippocampus-compose.service |
Debugging Workflow
- Check service status:
docker compose ps - View logs:
docker compose logs -f <service> - Check health:
docker compose exec <service> healthcheck-command - Inspect network:
docker compose exec envoy curl -s http://<service>:<port>/health
| Symptom | Action |
|---|---|
| Service not starting | Check logs, verify dependencies, check volumes |
| Connection refused | Verify network, check service health |
| GPU not available | Check nvidia-smi, verify runtime configuration |
| Model download failed | Check HF_HUB_TOKEN, verify network access |
Reaching the Stack from the claudex Sandbox
| Need | Route |
|---|---|
| Logs | journalctl -u hippocampus-compose.service |
| Web UI, HTTP API | http://{service}.127.0.0.1.nip.io |
| Datastore query, health endpoint | The port the service publishes on 127.0.0.1 - redis-cli, mysql and mc are absent, so drive it with curl or python3 |
| GPU state | nvidia-smi directly, not docker compose exec dcgm-exporter nvidia-smi |
Service status, exec, up/down/restart, volume contents |
Ask the user to run that docker compose subcommand on the host |
Every service's output reaches the journal of hippocampus-compose.service.
journalctl -u hippocampus-compose.service -f
journalctl -u hippocampus-compose.service --no-pager -o cat | grep '^comfyui-1 '
Each line keeps the <service>-1 | prefix docker compose up writes, so grep selects one service the way docker compose logs <service> would.
Reading Traces
An application run on the host that sets OTEL_EXPORTER_OTLP_ENDPOINT=https://opentelemetry-collector.127.0.0.1.nip.io, such as through its .env under make dev, sends its traces to this stack's Tempo, read through http://grafana.127.0.0.1.nip.io rather than the minikube Grafana.
GRAFANA=http://grafana.127.0.0.1.nip.io
TEMPO="$GRAFANA/api/datasources/proxy/uid/$(curl -sS $GRAFANA/api/datasources/name/Tempo | python3 -c 'import json,sys;print(json.load(sys.stdin)["uid"])')"
curl -sS -G "$TEMPO/api/search" --data-urlencode 'q={resource.service.name="<OTEL_SERVICE_NAME>"}' --data-urlencode "start=$(date -d '1 hour ago' +%s)" --data-urlencode "end=$(date +%s)"
curl -sS "$TEMPO/api/traces/<traceID>" | python3 -c 'import json,sys;[print(p["name"],(int(p["endTimeUnixNano"])-int(p["startTimeUnixNano"]))/1e9) for b in json.load(sys.stdin)["batches"] for s in b["scopeSpans"] for p in s["spans"]]'
Volume Management
# List volumes
docker volume ls | grep hippocampus
# Inspect volume
docker volume inspect hippocampus_comfyui-models
# Access volume data via ephemeral-container
docker compose exec ephemeral-container ls /home/nonroot/ComfyUI/models
Reference
If managing AI/ML services: See AI/ML Services