mcptesta/DOCKER.md

MCPTesta Docker Environment

A comprehensive Docker Compose setup for MCPTesta documentation with development and production configurations.

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Caddy external network created: make caddy-network

Development Environment

# Clone and setup
git clone <repository>
cd mcptesta

# Start development environment
make up
# OR manually:
# make setup && make dev

# View logs
make logs-live

# Access the site
open http://mcptesta.l.supported.systems

Production Environment

# Switch to production mode
make env-prod

# Start production environment
make prod

# Monitor production
make prod-logs

Architecture

Services

docs (Documentation Site)

• Development: Astro with hot reloading and volume mounts
• Production: Multi-stage build with nginx serving static files
• Features:
  • Automatic HTTPS via Caddy reverse proxy
  • Health checks and logging
  • Security headers and content optimization
  • Resource limits and monitoring

Networks

caddy (External)

• Connects documentation to Caddy reverse proxy
• Provides automatic HTTPS and load balancing
• Must be created externally: docker network create caddy

monitoring (Internal)

• Service monitoring and health checks
• Log aggregation and metrics collection

internal (Build-only)

• Isolated network for build processes
• Production image building and artifact handling

Volumes

Development

• docs_dev_cache: Astro build cache for faster rebuilds
• dev_data: SQLite database for development testing
• dev_redis: Redis cache for development

Production

• docs_build: Production build artifacts
• Persistent storage for static assets

Configuration

Environment Variables (.env)

# Project isolation
COMPOSE_PROJECT=mcptesta

# Environment mode
NODE_ENV=development  # or 'production'

# Domain configuration
DOCS_DOMAIN=mcptesta.l.supported.systems

# Resource limits
DOCS_MEMORY_LIMIT=512m
DOCS_CPU_LIMIT=0.5

# Health check configuration
HEALTH_CHECK_INTERVAL=30s
HEALTH_CHECK_TIMEOUT=10s
HEALTH_CHECK_RETRIES=3

Caddy Integration

The documentation site integrates with caddy-docker-proxy using labels:

labels:
  caddy: mcptesta.l.supported.systems
  caddy.reverse_proxy: "{{upstreams 4321}}"
  caddy.encode: gzip
  caddy.header.Cache-Control: "public, max-age=31536000"

Development Features

Hot Reloading

• Source files mounted as volumes
• Astro dev server with automatic rebuilds
• LiveReload integration for instant updates

Debugging

# Access container shell
make shell

# View real-time logs
make logs-live

# Check container health
make health

# Debug network connectivity
make network

File Watching

# Enable file watcher (requires inotify-tools)
docker compose --profile watcher up -d docs-watcher

# Manual watch mode
make watch

Production Features

Security

• Read-only root filesystem
• Non-root user execution
• Security headers and content policies
• Minimal attack surface with Alpine Linux

Performance

• Multi-stage builds for minimal image size
• Gzip/Zstd compression
• Static asset caching
• Resource limits and health monitoring

Monitoring

# Enable production monitoring
docker compose --profile monitoring up -d

# Check logs
make prod-logs

# View metrics
docker compose exec docs-monitor wget -qO- http://localhost:9100/metrics

Available Commands (Makefile)

Development

• make dev - Start development environment
• make dev-detached - Start in background
• make dev-logs - Follow development logs

Production

• make prod - Start production environment
• make prod-build - Build production images
• make prod-logs - Follow production logs

Management

• make build - Build development images
• make rebuild - Rebuild without cache
• make clean - Stop and remove containers/volumes
• make deep-clean - Full cleanup including images

Monitoring

• make logs - Show all logs
• make status - Container status
• make health - Health check status
• make restart - Restart services

Utilities

• make shell - Access container shell
• make test - Run health tests
• make network - Show network info
• make env - Show environment config

Environment

• make env-dev - Switch to development
• make env-prod - Switch to production
• make setup - Initial setup

File Structure

mcptesta/
├── .env                          # Environment configuration
├── docker-compose.yml           # Main compose file
├── docker-compose.dev.yml       # Development overrides
├── docker-compose.prod.yml      # Production overrides
├── Makefile                     # Management commands
├── DOCKER.md                    # This documentation
├── docs/
│   ├── Dockerfile               # Multi-stage documentation build
│   ├── package.json             # Node.js dependencies
│   ├── astro.config.mjs         # Astro configuration
│   └── src/                     # Documentation source
├── config/
│   ├── nginx-dev.conf           # Development nginx config
│   └── fluent-bit.conf          # Production logging config
└── scripts/                     # Utility scripts

Troubleshooting

Common Issues

Container won't start

# Check logs
make logs

# Verify environment
make env

# Check network
make network

Caddy network missing

# Create external network
make caddy-network
# OR manually:
# docker network create caddy

Permission issues

# Fix file permissions
sudo chown -R $USER:$USER docs/
sudo chmod -R 755 docs/

Port conflicts

# Check port usage
netstat -tlnp | grep :4321

# Modify port in .env
echo "DOCS_PORT=4322" >> .env

Debug Commands

# Full debug information
make debug

# Container inspection
docker compose exec docs sh -c "id && ls -la && env"

# Network connectivity
docker compose exec docs wget -qO- http://localhost:4321/

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

Health Checks

Health checks are configured for all services:

• Interval: 30 seconds
• Timeout: 10 seconds
• Retries: 3
• Start Period: 40 seconds

# Check health status
make health

# Manual health check
docker compose exec docs wget --spider -q http://localhost:4321/

Integration with MCPTesta

This Docker environment is designed to work seamlessly with the MCPTesta project:

Documentation Integration

• Astro/Starlight serves the Diátaxis-structured documentation
• Hot reloading for documentation development
• Integration with MCPTesta's existing docs/ structure

Development Workflow

• Local MCPTesta development with live documentation
• Testing documentation changes in real-time
• Production-ready deployment pipeline

CI/CD Integration

• Production builds for deployment
• Health checks for deployment validation
• Logging and monitoring for production environments

Best Practices

Development

1. Always use make commands for consistency
2. Check logs regularly: make logs-live
3. Use development environment for documentation editing
4. Test production builds before deployment

Production

1. Use production environment for staging/production
2. Monitor resource usage and health
3. Enable logging for production troubleshooting
4. Regular backups of persistent volumes

Security

1. Keep base images updated
2. Review security headers configuration
3. Monitor access logs
4. Use read-only filesystems in production

This Docker environment provides a robust, scalable, and secure foundation for MCPTesta documentation development and deployment.