mcptesta/README-DOCKER.md

# MCPTesta Docker Environment

🐳 **Comprehensive Docker Compose setup for MCPTesta documentation with development and production configurations.**

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose installed
- Make utility
- Internet connection for downloading base images

### One-Command Setup
```bash
make up
```

This will:
1. Validate your environment
2. Create required networks
3. Build and start the documentation site
4. Make it available at `http://mcptesta.l.supported.systems`

## 📋 Available Commands

### 🔧 Quick Start
```bash
make validate    # Validate setup
make setup      # Initial setup + validation
make up         # Complete setup and start dev environment
```

### 🔨 Development
```bash
make dev            # Start development with hot reloading
make dev-detached   # Start development in background
make dev-logs       # Follow development logs
```

### 🏭 Production
```bash
make env-prod   # Switch to production mode
make prod       # Start production environment
make prod-logs  # Follow production logs
```

### 📊 Monitoring
```bash
make status     # Show container status
make health     # Check health status
make logs       # Show all logs
make logs-live  # Follow all logs in real-time
```

### 🛠️ Management
```bash
make build      # Build images
make rebuild    # Rebuild without cache
make restart    # Restart all services
make clean      # Stop and cleanup
make deep-clean # Full cleanup including images
```

### 🐛 Debugging
```bash
make shell      # Access container shell
make debug      # Show comprehensive debug info
make network    # Show network information
```

## 🏗️ Architecture

### Services

#### `docs` - Documentation Site
- **Development**: Astro with hot reloading
- **Production**: Static build served by nginx
- **Domain**: `mcptesta.l.supported.systems`
- **Port**: 4321
- **Features**: HTTPS, caching, compression, security headers

### Networks

#### `caddy` (External)
- Reverse proxy network for automatic HTTPS
- Shared with other projects using caddy-docker-proxy

#### `monitoring` (Internal)
- Service health monitoring
- Metrics collection

### Volumes

#### Development
- Live code mounting for hot reloading
- Separate node_modules volume
- Build cache for performance

#### Production
- Static build artifacts
- Optimized for performance and security

## ⚙️ Configuration

### Environment Variables (.env)
```bash
# Core configuration
COMPOSE_PROJECT=mcptesta
NODE_ENV=development
DOCS_DOMAIN=mcptesta.l.supported.systems

# Resource limits
DOCS_MEMORY_LIMIT=512m
DOCS_CPU_LIMIT=0.5

# Health checks
HEALTH_CHECK_INTERVAL=30s
HEALTH_CHECK_TIMEOUT=10s
HEALTH_CHECK_RETRIES=3
```

### Environment Modes

#### Development Mode
- Hot reloading enabled
- Volume mounts for live editing
- Verbose logging
- Relaxed security settings
- Debug ports exposed

#### Production Mode
- Static build optimization
- Read-only filesystem
- Enhanced security headers
- Resource limits enforced
- Monitoring enabled

## 🔄 Switching Between Modes

```bash
# Switch to development
make env-dev
make dev

# Switch to production
make env-prod
make prod
```

## 🎯 Integration Features

### Caddy Integration
Automatic reverse proxy with:
- HTTPS certificates via Let's Encrypt
- Load balancing
- Compression (gzip/zstd)
- Security headers
- Caching policies

### Hot Reloading
Development environment supports:
- Astro dev server with instant rebuilds
- File watching with automatic restarts
- LiveReload integration
- Source map support

### Security
Production environment includes:
- Non-root user execution
- Read-only root filesystem  
- Security headers (HSTS, CSP, etc.)
- Minimal attack surface
- Regular security updates

## 📁 File Structure

```
mcptesta/
├── .env                          # Environment configuration
├── docker-compose.yml           # Main compose configuration  
├── docker-compose.dev.yml       # Development overrides
├── docker-compose.prod.yml      # Production overrides
├── Makefile                     # Management commands
├── DOCKER.md                    # Detailed documentation
├── README-DOCKER.md             # This quick reference
├── docs/
│   ├── Dockerfile               # Multi-stage documentation build
│   ├── .dockerignore            # Build optimization
│   ├── package.json             # Node.js dependencies
│   └── src/                     # Documentation source
├── config/
│   ├── nginx-dev.conf           # Development proxy config
│   └── fluent-bit.conf          # Production logging
└── scripts/
    ├── health-check.sh          # Container health validation
    ├── start-docs.sh            # Container startup script
    └── validate-setup.sh        # Environment validation
```

## 🧪 Testing & Validation

### Health Checks
Comprehensive health monitoring:
```bash
# Manual health check
make health

# Container-level health check
docker compose exec docs /app/scripts/health-check.sh
```

### Validation
Pre-flight validation:
```bash
# Validate complete setup
make validate

# Check specific components
docker compose config     # Validate compose files
./scripts/validate-setup.sh  # Full environment check
```

## 🚨 Troubleshooting

### Common Issues

#### "Caddy network not found"
```bash
make caddy-network
```

#### "Port 4321 already in use"
```bash
# Check what's using the port
netstat -tlnp | grep :4321

# Or change port in .env
echo "DOCS_PORT=4322" >> .env
```

#### "Permission denied" errors
```bash
# Fix ownership
sudo chown -R $USER:$USER docs/

# Fix permissions  
chmod +x scripts/*.sh
```

#### Container won't start
```bash
# Check logs
make logs

# Debug container
make shell

# Full debug info
make debug
```

### Debug Commands

```bash
# Container status
make status

# Network connectivity  
make network

# Resource usage
docker stats $(docker compose ps -q)

# Validate configuration
docker compose config

# Test health endpoint
curl -f http://mcptesta.l.supported.systems/ || echo "Site not accessible"
```

## 🎨 Customization

### Custom Domain
```bash
# Change domain in .env
DOCS_DOMAIN=mydocs.example.com

# Restart services
make restart
```

### Resource Limits
```bash
# Modify .env
DOCS_MEMORY_LIMIT=1g
DOCS_CPU_LIMIT=1.0

# Apply changes
make restart
```

### Additional Services
Add to `docker-compose.yml`:
```yaml
my-service:
  image: my-image:latest
  networks:
    - caddy
  labels:
    caddy: myservice.l.supported.systems
    caddy.reverse_proxy: "{{upstreams 8080}}"
```

## 🔗 Related Documentation

- [DOCKER.md](./DOCKER.md) - Comprehensive Docker documentation
- [docs/README.md](./docs/README.md) - Documentation site details
- [MCPTesta README](./README.md) - Main project documentation

## 💡 Pro Tips

1. **Use make commands** - They handle complexity and provide consistent behavior
2. **Check logs regularly** - `make logs-live` shows real-time activity
3. **Validate before changes** - `make validate` catches issues early
4. **Use development mode** - Hot reloading makes documentation editing fast
5. **Monitor resources** - `make debug` shows comprehensive system info
6. **Keep it clean** - `make clean` prevents disk space issues

---

**Happy Dockerizing! 🐳**