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