# 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 ```bash # Clone and setup git clone 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 ```bash # 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) ```bash # 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: ```yaml 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 ```bash # Access container shell make shell # View real-time logs make logs-live # Check container health make health # Debug network connectivity make network ``` ### File Watching ```bash # 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 ```bash # 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 ```bash # Check logs make logs # Verify environment make env # Check network make network ``` #### Caddy network missing ```bash # Create external network make caddy-network # OR manually: # docker network create caddy ``` #### Permission issues ```bash # Fix file permissions sudo chown -R $USER:$USER docs/ sudo chmod -R 755 docs/ ``` #### Port conflicts ```bash # Check port usage netstat -tlnp | grep :4321 # Modify port in .env echo "DOCS_PORT=4322" >> .env ``` ### Debug Commands ```bash # 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 ```bash # 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.