learning_ai_common_plat/AI.dev/SKILLS/docker-compose.md

Docker Compose Skill

Description: Run the entire application stack using Docker Compose for clean, isolated environments.

When to Use

• On networks without SSL-intercepting proxy
• For CI/CD pipelines
• When you need reproducible environments
• To avoid local dependency conflicts
• For demos and presentations

Prerequisites

• Docker Desktop running
• Sufficient RAM (8GB+ recommended)
• No SSL-intercepting proxy (or use scripts/switch-network.sh home)

Required Environment Files

1. Root .env (learning_voice_ai_agent)
2. admin-dashboard-web/.env.local
3. user-dashboard-web/.env.local
4. tracker-dashboard-web/.env.local

Quick Start

cd $HOME/code/mygh/learning_voice_ai_agent

# Start all 10 containers
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Stop everything
docker compose down

Services Overview

Service	Container	Port	Image	Purpose
Loki	loki	3100	grafana/loki:3.3.2	Log aggregation
Grafana	grafana	3000	grafana/grafana:11.4.0	Monitoring dashboard
Traefik Gateway	gateway	80, 8080	traefik:v3.3	API gateway/load balancer
Backend API	backend	8000	backend/Dockerfile	Python FastAPI backend
Admin Dashboard	admin-dashboard	3001	admin-dashboard-web/Dockerfile	Next.js admin UI
User Dashboard	user-dashboard	3002	user-dashboard-web/Dockerfile	Next.js user portal
Tracker Dashboard	tracker-dashboard	3003	tracker-dashboard-web/Dockerfile	Next.js tracker UI
Growth Service	growth-service	4001	../learning_ai_common_plat/...	Fastify microservice
Billing Service	billing-service	4002	../learning_ai_common_plat/...	Fastify microservice
Platform Service	platform-service	4003	../learning_ai_common_plat/...	Fastify microservice
Tracker Service	tracker-service	4004	../learning_ai_common_plat/...	Fastify microservice

Traefik Routing (Port 80)

All APIs are accessible through port 80 with path-based routing:

Path Prefix	Routes to	Example
/api (catch-all)	Backend API	http://localhost/api/health
/health	Backend API	http://localhost/health
/api/invitations	Growth Service	http://localhost/api/invitations
/api/referrals	Growth Service	http://localhost/api/referrals
/api/promos	Growth Service	http://localhost/api/promos
/api/subscriptions	Billing Service	http://localhost/api/subscriptions
/api/payments	Billing Service	http://localhost/api/payments
/api/usage	Billing Service	http://localhost/api/usage
/api/plans	Billing Service	http://localhost/api/plans
/api/licenses	Billing Service	http://localhost/api/licenses
/api/stripe	Billing Service	http://localhost/api/stripe
/api/auth	Platform Service	http://localhost/api/auth
/api/audit	Platform Service	http://localhost/api/audit
/api/notifications	Platform Service	http://localhost/api/notifications
/api/flags	Platform Service	http://localhost/api/flags
/api/ratelimit	Platform Service	http://localhost/api/ratelimit
/api/items	Tracker Service	http://localhost/api/items
/api/tracker	Tracker Service	http://localhost/api/tracker

Direct Port Access

You can also access services directly on their ports:

• Backend API: http://localhost:8000
• Admin Dashboard: http://localhost:3001
• User Dashboard: http://localhost:3002
• Tracker Dashboard: http://localhost:3003
• Grafana: http://localhost:3000 (admin / lysnrai)
• Traefik Dashboard: http://localhost:8080

Common Operations

Rebuild After Code Changes

# Rebuild all images
docker compose build

# Rebuild specific service
docker compose build backend

# Restart with new images
docker compose up -d

View Logs

# All logs
docker compose logs -f

# Specific service
docker compose logs -f backend

# Last 100 lines
docker compose logs --tail=100

Debug a Container

# Get shell in container
docker compose exec backend sh

# Or for one-off commands
docker compose run --rm backend python --version

Clean Up

# Remove containers and networks
docker compose down

# Remove volumes (WARNING: deletes data)
docker compose down -v

# Remove images
docker compose down --rmi all

# Full reset
docker system prune -a

Observability

Grafana Dashboard

1. Open http://localhost:3000
2. Login with admin/lysnrai
3. View pre-configured dashboards for:
   • Service health
   • Request rates
   • Error rates
   • Resource usage

Log Aggregation

All services ship logs to Loki via the Docker driver:

• Logs are automatically collected
• Available in Grafana with Explore feature
• Use {container_name="backend"} to filter

Health Checks

# Check all services via Traefik
curl http://localhost/health

# Check individual services
docker compose exec backend curl http://localhost:8000/health

Troubleshooting

Container Won't Start

# Check logs
docker compose logs <service>

# Check if port is in use
lsof -i :8000

# Check resource usage
docker stats

Build Failures

• Python: Check backend/Dockerfile for Python version compatibility
• Node.js: Ensure package.json lock files are present
• SSL proxy: Docker builds will fail behind SSL-intercepting proxies

Performance Issues

# Check resource usage
docker stats

# Increase Docker memory limit in Docker Desktop
# Recommended: 8GB+ RAM, 4+ CPU cores

Network Issues

# Check network configuration
docker network ls
docker network inspect learning_voice_ai_agent_default

# Reset network
docker compose down
docker network prune
docker compose up -d

Production Considerations

• Environment variables: Use Docker secrets or external secret management
• Persistent data: Use named volumes for databases
• Resource limits: Set memory/CPU limits in docker-compose.yml
• Health checks: All services include health check endpoints
• Logging: Consider centralized logging in production

Notes

• Do NOT use behind SSL-intercepting proxies — breaks pip/npm installs inside containers
• All dashboards require output: "standalone" in next.config.ts (already configured)
• Env vars are injected via env_file in docker-compose.yml
• Images are multi-stage for optimal production size

Related Skills

• Local Development Setup - Alternative non-Docker setup
• Production Readiness - Validation before deployment
• Debug Service - Troubleshooting running services