CodeCompass MCP

# Docker Deployment Guide This guide covers how to deploy CodeCompass MCP using Docker containers, including development and production configurations. ## Quick Start ### Building the Image ```bash # Build production image ./scripts/docker-build.sh # Build development image ./scripts/docker-build.sh --dev # Build with custom tag ./scripts/docker-build.sh -t v1.0.0 ``` ### Running the Container ```bash # Run with defaults ./scripts/docker-run.sh # Run with environment variables ./scripts/docker-run.sh -e GITHUB_TOKEN=your_token -e OPENROUTER_API_KEY=your_key # Run with environment file ./scripts/docker-run.sh --env-file .env # Run interactively ./scripts/docker-run.sh --interactive ``` ### Viewing Logs ```bash # View last 100 lines ./scripts/docker-logs.sh # Follow logs ./scripts/docker-logs.sh -f # View all logs with timestamps ./scripts/docker-logs.sh --all --timestamps ``` ## Docker Images ### Production Image (`Dockerfile`) The production image is optimized for: - Minimal size using Alpine Linux - Non-root user for security - Multi-stage build for efficiency - Health checks for monitoring - Proper signal handling Key features: - Based on `node:18-alpine` - Runs as non-root user `mcpuser` - Includes health check endpoint - Optimized for container environments ### Development Image (`Dockerfile.dev`) The development image includes: - Source code mounted as volume - Development dependencies - Hot reloading support - Debug tools - Interactive shell access ## Environment Variables ### Required Variables - `GITHUB_TOKEN`: GitHub personal access token for API access - `OPENROUTER_API_KEY`: OpenRouter API key for AI features ### Optional Variables - `NODE_ENV`: Environment (development/production) - `LOG_LEVEL`: Logging level (debug/info/warn/error) - `MAX_RESPONSE_TOKENS`: Maximum response size - `MAX_FILE_CONTENT_LENGTH`: Maximum file content size - `RATE_LIMIT_REQUESTS`: Rate limit for requests - `RATE_LIMIT_WINDOW`: Rate limit window in seconds ### Configuration Example Create a `.env` file: ```bash # Required GITHUB_TOKEN=ghp_your_github_token_here OPENROUTER_API_KEY=sk-or-your_openrouter_key_here # Optional NODE_ENV=production LOG_LEVEL=info MAX_RESPONSE_TOKENS=25000 MAX_FILE_CONTENT_LENGTH=5000 RATE_LIMIT_REQUESTS=100 RATE_LIMIT_WINDOW=3600 ``` ## Docker Compose Use Docker Compose for more complex deployments: ```bash # Start services docker-compose up -d # View logs docker-compose logs -f # Stop services docker-compose down ``` The `docker-compose.yml` includes: - CodeCompass MCP service - Environment configuration - Volume mounts - Health checks - Resource limits - Logging configuration ### Production Docker Compose For production with external logging: ```yaml version: '3.8' services: codecompass-mcp: image: codecompass-mcp:latest container_name: codecompass-mcp-prod restart: unless-stopped env_file: .env.production environment: - NODE_ENV=production - LOG_LEVEL=info healthcheck: test: ["CMD", "node", "-e", "console.log('Health check')"] interval: 30s timeout: 10s retries: 3 start_period: 10s resources: limits: memory: 512M cpus: '0.5' reservations: memory: 256M cpus: '0.25' logging: driver: json-file options: max-size: 10m max-file: 3 networks: - codecompass-network networks: codecompass-network: driver: bridge ``` ## Scripts Overview ### `docker-build.sh` Builds Docker images with various options: ```bash # Available options ./scripts/docker-build.sh --help # Examples ./scripts/docker-build.sh # Default build ./scripts/docker-build.sh --dev # Development build ./scripts/docker-build.sh -t v1.0.0 --push # Build and push ./scripts/docker-build.sh --build-arg NODE_ENV=production ``` ### `docker-run.sh` Runs containers with flexible configuration: ```bash # Available options ./scripts/docker-run.sh --help # Examples ./scripts/docker-run.sh # Default run ./scripts/docker-run.sh --interactive # Interactive mode ./scripts/docker-run.sh --foreground # Foreground mode ./scripts/docker-run.sh --remove-existing # Remove existing container ./scripts/docker-run.sh -v /host/data:/app/data # Mount volume ``` ### `docker-logs.sh` Views container logs with various options: ```bash # Available options ./scripts/docker-logs.sh --help # Examples ./scripts/docker-logs.sh # Last 100 lines ./scripts/docker-logs.sh -f # Follow logs ./scripts/docker-logs.sh --timestamps # Show timestamps ./scripts/docker-logs.sh --all # Show all logs ``` ## Development Workflow ### 1. Development Setup ```bash # Build development image ./scripts/docker-build.sh --dev # Run in development mode ./scripts/docker-run.sh --interactive -v $(pwd):/app # Or use docker-compose docker-compose -f docker-compose.dev.yml up ``` ### 2. Testing Changes ```bash # Run tests in container docker exec -it codecompass-mcp npm test # Run linting docker exec -it codecompass-mcp npm run lint # Run type checking docker exec -it codecompass-mcp npm run type-check ``` ### 3. Production Deployment ```bash # Build production image ./scripts/docker-build.sh -t production # Run with production configuration ./scripts/docker-run.sh -i codecompass-mcp:production --env-file .env.production # Or use docker-compose docker-compose -f docker-compose.prod.yml up -d ``` ## Security Best Practices ### 1. Non-Root User Both images run as non-root user `mcpuser` (UID 1000): ```dockerfile # Create non-root user RUN addgroup -g 1000 mcpuser && \ adduser -D -s /bin/sh -u 1000 -G mcpuser mcpuser # Switch to non-root user USER mcpuser ``` ### 2. Environment Variables - Never commit secrets to version control - Use `.env` files for local development - Use container orchestration secrets for production - Rotate API keys regularly ### 3. Network Security - Use custom networks for container isolation - Expose only necessary ports - Use reverse proxy for external access - Enable TLS termination at load balancer ### 4. Resource Limits Always set resource limits: ```yaml resources: limits: memory: 512M cpus: '0.5' reservations: memory: 256M cpus: '0.25' ``` ## Monitoring and Observability ### Health Checks Health checks are built into the Docker images: ```bash # Manual health check docker exec codecompass-mcp node -e "console.log('Health check')" # Docker health status docker inspect codecompass-mcp | grep -A 10 Health ``` ### Logging Structured logging is configured for container environments: ```bash # View structured logs docker logs codecompass-mcp | jq . # Filter by log level docker logs codecompass-mcp | jq 'select(.level == "ERROR")' # Follow logs with timestamps docker logs -f --timestamps codecompass-mcp ``` ### Metrics The logger provides basic metrics: ```bash # Get server stats (if exposed) docker exec codecompass-mcp node -e " import('./build/utils/logger.js').then(m => console.log(JSON.stringify(m.log.getStats(), null, 2)) ) " ``` ## Troubleshooting ### Common Issues 1. **Container won't start** ```bash # Check logs ./scripts/docker-logs.sh # Check container status docker ps -a # Inspect container docker inspect codecompass-mcp ``` 2. **Environment variables not loaded** ```bash # Check environment in container docker exec codecompass-mcp env | grep -E "(GITHUB|OPENROUTER)" # Check .env file format cat .env ``` 3. **Permission errors** ```bash # Check file permissions ls -la # Fix script permissions chmod +x scripts/*.sh ``` 4. **Memory issues** ```bash # Check memory usage docker stats codecompass-mcp # Adjust memory limits docker update --memory=1g codecompass-mcp ``` ### Debug Mode Run container in debug mode: ```bash # Interactive debug session ./scripts/docker-run.sh --interactive # Or with debug logging ./scripts/docker-run.sh -e LOG_LEVEL=debug ``` ## Advanced Configuration ### Multi-Stage Builds The production Dockerfile uses multi-stage builds: ```dockerfile # Build stage FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production # Runtime stage FROM node:18-alpine AS runtime WORKDIR /app COPY --from=builder /app/node_modules ./node_modules COPY . . ``` ### Container Orchestration For Kubernetes deployment: ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: codecompass-mcp spec: replicas: 2 selector: matchLabels: app: codecompass-mcp template: metadata: labels: app: codecompass-mcp spec: containers: - name: codecompass-mcp image: codecompass-mcp:latest ports: - containerPort: 3000 env: - name: GITHUB_TOKEN valueFrom: secretKeyRef: name: codecompass-secrets key: github-token - name: OPENROUTER_API_KEY valueFrom: secretKeyRef: name: codecompass-secrets key: openrouter-api-key resources: requests: memory: "256Mi" cpu: "250m" limits: memory: "512Mi" cpu: "500m" ``` ## References - [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/) - [Docker Compose Documentation](https://docs.docker.com/compose/) - [Node.js Docker Guide](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) - [Container Security Guide](https://docs.docker.com/engine/security/)