# 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

```bash
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

```bash
# Rebuild all images
docker compose build

# Rebuild specific service
docker compose build backend

# Restart with new images
docker compose up -d
```

### View Logs

```bash
# All logs
docker compose logs -f

# Specific service
docker compose logs -f backend

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

### Debug a Container

```bash
# Get shell in container
docker compose exec backend sh

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

### Clean Up

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check resource usage
docker stats

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

### Network Issues

```bash
# 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](./local-development.md) - Alternative non-Docker setup
- [Production Readiness](./production-readiness.md) - Validation before deployment
- [Debug Service](./debug-service.md) - Troubleshooting running services