# Docker Deployment Guide - Komodo MCP Server
Comprehensive guide for deploying the Komodo MCP server using Docker and Docker Compose.
## Table of Contents
- [Quick Start](#quick-start)
- [Prerequisites](#prerequisites)
- [Building the Image](#building-the-image)
- [Running Containers](#running-containers)
- [Deployment Profiles](#deployment-profiles)
- [Environment Configuration](#environment-configuration)
- [Port Mapping](#port-mapping)
- [Health Checks](#health-checks)
- [Logging](#logging)
- [Scaling](#scaling)
- [Load Balancing](#load-balancing)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Production Checklist](#production-checklist)
## Quick Start
### Using Deployment Script
```bash
# Make script executable
chmod +x scripts/docker-deploy.sh
# Build Docker image
./scripts/docker-deploy.sh build
# Start default instance
./scripts/docker-deploy.sh start
# Check health
./scripts/docker-deploy.sh health
# View logs
./scripts/docker-deploy.sh logs
```
### Using Docker Compose Directly
```bash
# Build image
docker-compose build
# Start default instance
docker-compose up -d komodo-mcp-1
# Check status
docker-compose ps
# View logs
docker-compose logs -f komodo-mcp-1
```
## Prerequisites
- Docker 20.10 or later
- Docker Compose 1.29 or later
- Node.js 20+ (for local builds)
- Git (for version control)
### Install Docker
**macOS:**
```bash
brew install docker docker-compose
# or install Docker Desktop which includes both
```
**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install docker.io docker-compose
sudo usermod -aG docker $USER
```
**Windows:**
Download and install Docker Desktop from https://www.docker.com/products/docker-desktop
## Building the Image
### Production Build
Build the multi-stage Docker image for production deployment:
```bash
# Build with default tag
docker build -t komodo-mcp:latest .
# Build with specific tag
docker build -t komodo-mcp:v1.0.0 .
# Build with custom base image
docker build -t komodo-mcp:latest \
--build-arg NODE_VERSION=20-alpine .
```
### Development Build
Build image with development tools and debugging:
```bash
# Build development image
docker build -f Dockerfile.dev -t komodo-mcp:dev .
# Or use deployment script
./scripts/docker-deploy.sh build-dev
```
### Using Deployment Script
```bash
# Build production image
./scripts/docker-deploy.sh build
# Build development image
./scripts/docker-deploy.sh build-dev
```
## Running Containers
### Basic Usage
Start a single instance:
```bash
# Using Docker Compose
docker-compose up -d komodo-mcp-1
# Using deployment script
./scripts/docker-deploy.sh start
# Verify container is running
docker-compose ps komodo-mcp-1
```
### Configuration
Before starting containers, configure environment variables:
```bash
# Copy example environment file
cp config/.env.example .env
# Edit with your Komodo API credentials
nano .env
# Verify environment file
cat .env
```
Required environment variables:
- `KOMODO_URL`: Komodo API server URL
- `KOMODO_API_KEY`: API key for authentication
- `KOMODO_API_SECRET`: API secret for authentication
### Starting Container
```bash
# Start and follow logs
docker-compose up komodo-mcp-1
# Start in background
docker-compose up -d komodo-mcp-1
# Start with deployment script
./scripts/docker-deploy.sh start default
```
### Stopping Container
```bash
# Stop running container
docker-compose stop komodo-mcp-1
# Stop all containers
docker-compose stop
# Remove stopped container
docker-compose rm komodo-mcp-1
# Stop and remove
docker-compose down komodo-mcp-1
```
## Deployment Profiles
Deployment profiles enable different configurations for various use cases.
### Profile: Default
Single instance deployment (primary use case):
```bash
# Start default profile
docker-compose up -d
# Or
./scripts/docker-deploy.sh start default
# Services running:
# - komodo-mcp-1: port 1111
```
### Profile: Scaled
Three instances for high availability:
```bash
# Start scaled profile
docker-compose --profile scaled up -d
# Or
./scripts/docker-deploy.sh start scaled
# Services running:
# - komodo-mcp-1: port 1111
# - komodo-mcp-2: port 1112
# - komodo-mcp-3: port 1113
```
### Profile: Load-Balanced
Scaled deployment with Nginx load balancer:
```bash
# Start load-balanced profile
docker-compose --profile scaled --profile load-balanced up -d
# Or
./scripts/docker-deploy.sh start load-balanced
# Services running:
# - nginx-lb: port 1110 (load balancer)
# - komodo-mcp-1: port 1111
# - komodo-mcp-2: port 1112
# - komodo-mcp-3: port 1113
```
### Profile: Development
Development environment with hot reload and debugging:
```bash
# Start development profile
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
# Or
./scripts/docker-deploy.sh start dev
# Services running:
# - komodo-mcp-1: port 1111 (with hot reload)
# - Debug port: 9229
```
## Environment Configuration
### Setting Environment Variables
Create `.env` file from template:
```bash
cp config/.env.example .env
```
Edit `.env` with your configuration:
```bash
# Required - Komodo API Connection
KOMODO_URL=https://komodo.example.com
KOMODO_API_KEY=km_key_your_api_key_here
KOMODO_API_SECRET=km_secret_your_api_secret_here
# Optional - Timeouts and Retries
KOMODO_TIMEOUT=30000
KOMODO_RETRY_COUNT=3
KOMODO_RETRY_DELAY=1000
# Optional - Logging
KOMODO_LOG_LEVEL=info
# Optional - SSL Verification
KOMODO_SSL_VERIFY=true
```
### Environment Variables in Containers
Variables available in running containers:
| Variable | Default | Description |
|----------|---------|-------------|
| `KOMODO_URL` | Required | Komodo API server URL |
| `KOMODO_API_KEY` | Required | API key for authentication |
| `KOMODO_API_SECRET` | Required | API secret for authentication |
| `KOMODO_TIMEOUT` | 30000 | Request timeout (ms) |
| `KOMODO_RETRY_COUNT` | 3 | Number of retries |
| `KOMODO_RETRY_DELAY` | 1000 | Delay between retries (ms) |
| `KOMODO_LOG_LEVEL` | info | Logging level |
| `KOMODO_SSL_VERIFY` | true | Verify SSL certificates |
| `INSTANCE_ID` | Varies | Instance identifier |
| `INSTANCE_PORT` | 1111 | Container port |
### Override Environment Variables
Override variables at runtime:
```bash
# Using environment flag
docker-compose run -e KOMODO_LOG_LEVEL=debug komodo-mcp-1
# Using shell export
export KOMODO_LOG_LEVEL=debug
docker-compose up -d komodo-mcp-1
# Using .env file
docker-compose -f docker-compose.yml --env-file .env.production up -d
```
## Port Mapping
Port mapping for different deployment profiles:
### Default Profile
```
Container Port Host Port Service
1111 1111 komodo-mcp-1
9229 - Debug (not exposed)
```
### Scaled Profile
```
Container Port Host Port Service
1111 1111 komodo-mcp-1
1111 1112 komodo-mcp-2
1111 1113 komodo-mcp-3
```
### Load-Balanced Profile
```
Container Port Host Port Service
80 1110 nginx-lb (load balancer)
1111 1111 komodo-mcp-1
1111 1112 komodo-mcp-2
1111 1113 komodo-mcp-3
```
### Development Profile
```
Container Port Host Port Service
1111 1111 komodo-mcp-1 (with hot reload)
9229 9229 Debug inspector
```
### Custom Port Mapping
Override ports in docker-compose.yml or use command line:
```bash
# Override port mapping
docker run -p 8888:1111 komodo-mcp:latest
# Multiple port mappings
docker-compose -f docker-compose.yml \
-p komodo-mcp-1 -e KOMODO_PORT=2222 \
up -d
```
## Health Checks
Health checks monitor container status and enable automatic restart policies.
### Built-in Health Check
The Dockerfile includes a health check that verifies port connectivity:
```yaml
healthcheck:
test: ["CMD", "node", "-e", "require('net').connect(1111, '127.0.0.1').on('connect', () => process.exit(0)).on('error', () => process.exit(1))"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
```
### Check Container Health
```bash
# View health status
docker ps --format "table {{.Names}}\t{{.Status}}"
# Expected output:
# NAMES STATUS
# komodo-mcp-1 Up 2 minutes (healthy)
# Check specific container
docker inspect --format='{{.State.Health.Status}}' komodo-mcp-1
```
### Using Deployment Script
```bash
# Run health checks
./scripts/docker-deploy.sh health
# Output example:
# [SUCCESS] komodo-mcp-1 is healthy (port 1111)
# [SUCCESS] All 1 container(s) are healthy
```
### Custom Health Check
Modify healthcheck in docker-compose.yml:
```yaml
services:
komodo-mcp-1:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:1111/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
```
## Logging
Container logs provide visibility into server operations.
### View Logs
```bash
# View logs for specific instance
docker-compose logs komodo-mcp-1
# View logs for all containers
docker-compose logs
# Follow logs in real-time
docker-compose logs -f
# Follow specific container logs
docker-compose logs -f komodo-mcp-1
# Show last 100 lines
docker-compose logs --tail 100 komodo-mcp-1
```
### Using Deployment Script
```bash
# View logs for specific instance
./scripts/docker-deploy.sh logs komodo-mcp-1
# View logs for all containers
./scripts/docker-deploy.sh logs-all
# View specific number of lines
./scripts/docker-deploy.sh logs komodo-mcp-1 200
# Clean log files
./scripts/docker-deploy.sh clean-logs
```
### Log Configuration
Docker Compose log driver configuration in docker-compose.yml:
```yaml
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "10"
labels: "service=komodo-mcp-1"
```
Options:
- `max-size`: Maximum size of log file before rotation
- `max-file`: Maximum number of rotated log files to keep
- `labels`: Metadata labels for log entries
### Log Locations
Container logs stored locally:
```
./logs/
├── komodo-mcp-1/
│ └── *.log
├── komodo-mcp-2/
│ └── *.log
└── komodo-mcp-3/
└── *.log
```
## Scaling
Horizontal scaling for high availability and load distribution.
### Scale to Multiple Instances
Using deployment script:
```bash
# Scale to 3 instances
./scripts/docker-deploy.sh start scaled
# Verify running instances
docker-compose ps
# Check health of all instances
./scripts/docker-deploy.sh health
```
Using Docker Compose directly:
```bash
# Start all scaled services
docker-compose --profile scaled up -d
# View all running instances
docker-compose ps
# Scale existing service
docker-compose up -d --scale komodo-mcp=3
```
### Instance Configuration
Each instance can have:
- Dedicated port mapping
- Independent logs
- Separate environment overrides
- Resource limits
Example docker-compose.yml configuration:
```yaml
services:
komodo-mcp-1:
ports:
- "1111:1111"
environment:
INSTANCE_ID: "komodo-mcp-1"
INSTANCE_PORT: "1111"
komodo-mcp-2:
ports:
- "1112:1111"
environment:
INSTANCE_ID: "komodo-mcp-2"
INSTANCE_PORT: "1111"
```
### Resource Management
Limit resource usage per instance:
```yaml
services:
komodo-mcp-1:
deploy:
resources:
limits:
cpus: '1'
memory: 512M
reservations:
cpus: '0.5'
memory: 256M
```
## Load Balancing
Nginx load balancer distributes traffic across instances.
### Enable Load Balancing
```bash
# Start with load balancer
./scripts/docker-deploy.sh start load-balanced
# Or using Docker Compose
docker-compose --profile scaled --profile load-balanced up -d
# Verify services
docker-compose ps
```
### Load Balancer Access
Access load balancer:
```bash
# Load balancer endpoint
http://localhost:1110
# Health check endpoint
http://localhost:1110/health
# Metrics endpoint
http://localhost:1110/metrics
```
### Load Balancer Configuration
Nginx configuration in `config/nginx.conf`:
```nginx
upstream komodo_backend {
least_conn;
server komodo-mcp-1:1111 weight=3;
server komodo-mcp-2:1111 weight=2;
server komodo-mcp-3:1111 weight=2;
keepalive 32;
}
```
Load balancing algorithms:
- `least_conn`: Route to server with fewest connections
- `round_robin`: Route to each server in turn
- `ip_hash`: Route based on client IP
- `weighted`: Route based on weight values
### Direct Instance Access
Access individual instances directly (bypassing load balancer):
```bash
# Instance 1
curl http://localhost:1111
# Instance 2
curl http://localhost:1112
# Instance 3
curl http://localhost:1113
# Through load balancer
curl http://localhost:1110
```
## Development
Development environment with hot reload and debugging capabilities.
### Start Development Container
```bash
# Using deployment script
./scripts/docker-deploy.sh start dev
# Using Docker Compose
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
```
### Features
- Source code volume mount for hot reload
- Debug port exposed (9229)
- Development dependencies installed
- Detailed logging enabled
### Debugging
Connect debugger to port 9229:
**VS Code:**
Add to `.vscode/launch.json`:
```json
{
"type": "node",
"request": "attach",
"name": "Attach Docker Debug",
"port": 9229,
"address": "localhost",
"restart": true,
"skipFiles": ["<node_internals>/**"]
}
```
Start debugging:
1. Start development container
2. Open VS Code debug panel
3. Select "Attach Docker Debug"
4. Press F5
**Command Line:**
```bash
node inspect -p 9229
# Or use Node inspector
node --inspect-brk=0.0.0.0:9229 dist/index.js
```
### Hot Reload
Modify source code and changes reload automatically:
```bash
# Edit source file
nano src/index.ts
# Container automatically rebuilds and restarts
# Watch logs for confirmation
docker-compose logs -f komodo-mcp-1
```
### Stop Development Container
```bash
# Stop all development services
docker-compose -f docker-compose.yml -f docker-compose.dev.yml down
# Or
./scripts/docker-deploy.sh stop dev
```
## Troubleshooting
Common issues and solutions.
### Container Won't Start
```bash
# Check logs
docker-compose logs komodo-mcp-1
# Verify image exists
docker images | grep komodo-mcp
# Rebuild image
docker-compose build --no-cache komodo-mcp-1
```
**Common causes:**
- Missing environment variables
- Invalid Komodo API credentials
- Port already in use
- Insufficient disk space
### Connection Refused
```bash
# Verify container is running
docker-compose ps
# Check if port is accessible
nc -zv localhost 1111
# Or
telnet localhost 1111
# Check container network
docker-compose exec komodo-mcp-1 ping komodo-mcp-2
```
### Health Check Failing
```bash
# Check health status
docker inspect --format='{{json .State.Health}}' komodo-mcp-1 | jq
# View health events
docker events --filter "type=container" --filter "event=health_status"
# Run health check manually
docker-compose exec komodo-mcp-1 node -e "require('net').connect(1111, '127.0.0.1').on('connect', () => console.log('OK')).on('error', () => console.log('FAILED'))"
```
### Out of Disk Space
```bash
# Check disk usage
docker system df
# Clean up unused images
docker image prune
# Clean up unused containers
docker container prune
# Clean up volumes
docker volume prune
# Full cleanup
docker system prune -a
```
### High Memory Usage
```bash
# Check memory usage
docker stats
# Limit memory usage in docker-compose.yml
deploy:
resources:
limits:
memory: 512M
# Restart container with memory limit
docker-compose down
docker-compose up -d
```
### Network Issues
```bash
# Inspect network
docker network inspect komodo-network
# Test connectivity between containers
docker-compose exec komodo-mcp-1 ping komodo-mcp-2
# View network traffic
docker-compose exec komodo-mcp-1 netstat -tulpn
```
## Production Checklist
Pre-deployment verification for production environments.
### Security
- [ ] Use non-root user (configured in Dockerfile)
- [ ] Update to latest Node.js LTS image
- [ ] Enable SSL verification (`KOMODO_SSL_VERIFY=true`)
- [ ] Use secure secret management (Vault, AWS Secrets Manager)
- [ ] Rotate API keys periodically
- [ ] Configure firewall rules
- [ ] Enable container security scanning
### Performance
- [ ] Set appropriate resource limits
- [ ] Configure log rotation (max-size, max-file)
- [ ] Enable health checks
- [ ] Set restart policies to `unless-stopped`
- [ ] Test with production load
- [ ] Monitor CPU and memory usage
### Reliability
- [ ] Test failover with multiple instances
- [ ] Verify health check configuration
- [ ] Test graceful shutdown
- [ ] Implement monitoring and alerting
- [ ] Set up log aggregation
- [ ] Create backup/recovery procedures
### Operations
- [ ] Document deployment procedures
- [ ] Create runbooks for common issues
- [ ] Set up monitoring dashboard
- [ ] Configure alerting for failures
- [ ] Test incident response procedures
- [ ] Plan for capacity scaling
### Configuration
- [ ] Verify all environment variables set
- [ ] Test API connectivity
- [ ] Validate SSL certificates
- [ ] Check timezone settings
- [ ] Review logging configuration
- [ ] Verify network connectivity
### Deployment
- [ ] Test full deployment process
- [ ] Verify all instances healthy
- [ ] Test load balancer functionality
- [ ] Confirm logs are being collected
- [ ] Verify monitoring is active
- [ ] Test rollback procedure
## References
- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Nginx Documentation](https://nginx.org/en/docs/)
- [Node.js Best Practices](https://nodejs.org/en/docs/guides/)
- [Komodo API Documentation](../ENVIRONMENT.md)
