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

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

make validate    # Validate setup
make setup      # Initial setup + validation
make up         # Complete setup and start dev environment

🔨 Development

make dev            # Start development with hot reloading
make dev-detached   # Start development in background
make dev-logs       # Follow development logs

🏭 Production

make env-prod   # Switch to production mode
make prod       # Start production environment
make prod-logs  # Follow production logs

📊 Monitoring

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

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

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)

# 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

# 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:

# Manual health check
make health

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

Validation

Pre-flight validation:

# 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"

make caddy-network

"Port 4321 already in use"

# Check what's using the port
netstat -tlnp | grep :4321

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

"Permission denied" errors

# Fix ownership
sudo chown -R $USER:$USER docs/

# Fix permissions  
chmod +x scripts/*.sh

Container won't start

# Check logs
make logs

# Debug container
make shell

# Full debug info
make debug

Debug Commands

# 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

# Change domain in .env
DOCS_DOMAIN=mydocs.example.com

# Restart services
make restart

Resource Limits

# Modify .env
DOCS_MEMORY_LIMIT=1g
DOCS_CPU_LIMIT=1.0

# Apply changes
make restart

Additional Services

Add to docker-compose.yml:

my-service:
  image: my-image:latest
  networks:
    - caddy
  labels:
    caddy: myservice.l.supported.systems
    caddy.reverse_proxy: "{{upstreams 8080}}"

🔗 Related Documentation

• DOCKER.md - Comprehensive Docker documentation
• docs/README.md - Documentation site details
• MCPTesta README - 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! 🐳