claude-code-subagents-orchestrator/docs/DEPLOYMENT.md

Claude Code Sub-agents Orchestrator - A powerful MCP server for orchestrating multiple AI sub-agents for complex task execution in Claude Code

# Deployment Guide

## Overview

This guide covers deploying Claude Code Subagents Orchestrator in production environments, from simple single-instance deployments to enterprise-scale orchestrations.

## Deployment Options

### 1. Local Development
- Single developer machine
- Local Claude Code integration
- Development and testing

### 2. Team Deployment
- Shared development environments
- CI/CD integration
- Multi-developer access

### 3. Enterprise Deployment
- Production environments
- High availability
- Monitoring and logging
- Security compliance

## Pre-Deployment Checklist

### System Requirements

- [ ] Node.js 18+ installed and configured
- [ ] Claude Code installed on client machines
- [ ] Network connectivity to required services
- [ ] Adequate system resources (CPU, RAM, storage)
- [ ] Security policies reviewed and approved

### Security Requirements

- [ ] SSL/TLS certificates configured
- [ ] Firewall rules configured
- [ ] Authentication/authorization setup
- [ ] Data encryption at rest and in transit
- [ ] Audit logging enabled
- [ ] Security scanning completed

### Network Requirements

- [ ] Required ports open (default: 3000)
- [ ] DNS resolution configured
- [ ] Load balancer setup (if applicable)
- [ ] CDN configuration (if applicable)
- [ ] Backup connectivity options

## Deployment Methods

### Method 1: Direct Installation

#### Single Server Deployment

```bash
# 1. Install Node.js and npm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. Install orchestrator globally
sudo npm install -g claude-code-subagents-orchestrator

# 3. Create service user
sudo useradd --system --shell /bin/false orchestrator

# 4. Create systemd service
sudo tee /etc/systemd/system/claude-orchestrator.service > /dev/null <<EOF
[Unit]
Description=Claude Code Subagents Orchestrator
After=network.target

[Service]
Type=simple
User=orchestrator
WorkingDirectory=/opt/claude-orchestrator
ExecStart=/usr/bin/node /usr/lib/node_modules/claude-code-subagents-orchestrator/dist/server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target
EOF

# 5. Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable claude-orchestrator
sudo systemctl start claude-orchestrator
```

#### Multi-Server Deployment

For high availability, deploy multiple instances behind a load balancer:

```bash
# Load balancer configuration (nginx example)
upstream orchestrator_backend {
    server 10.0.1.10:3000 weight=1 max_fails=3 fail_timeout=30s;
    server 10.0.1.11:3000 weight=1 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:3000 weight=1 max_fails=3 fail_timeout=30s;
}

server {
    listen 80;
    server_name orchestrator.company.com;
    
    location / {
        proxy_pass http://orchestrator_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Method 2: Docker Deployment

#### Single Container

```bash
# Pull and run latest image
docker run -d \
  --name claude-orchestrator \
  --restart unless-stopped \
  -p 3000:3000 \
  -v orchestrator_data:/app/data \
  -v orchestrator_logs:/app/logs \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  ghcr.io/anthropic/claude-code-subagents-orchestrator:latest
```

#### Docker Compose Production

```yaml
# docker-compose.prod.yml
version: '3.8'

services:
  orchestrator:
    image: ghcr.io/anthropic/claude-code-subagents-orchestrator:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
      - PORT=3000
    volumes:
      - orchestrator_data:/app/data
      - orchestrator_logs:/app/logs
      - ./config:/app/config:ro
    healthcheck:
      test: ["CMD", "node", "scripts/health-check.js", "--json"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '0.5'
        reservations:
          memory: 512M
          cpus: '0.25'

  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - orchestrator

volumes:
  orchestrator_data:
  orchestrator_logs:
```

#### Docker Swarm Deployment

```bash
# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.prod.yml orchestrator

# Scale services
docker service scale orchestrator_orchestrator=3
```

### Method 3: Kubernetes Deployment

#### Basic Kubernetes Deployment

```yaml
# kubernetes/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: claude-orchestrator

---
# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-orchestrator
  namespace: claude-orchestrator
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-orchestrator
  template:
    metadata:
      labels:
        app: claude-orchestrator
    spec:
      containers:
      - name: orchestrator
        image: ghcr.io/anthropic/claude-code-subagents-orchestrator:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
        - name: LOG_LEVEL
          value: "info"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5

---
# kubernetes/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: claude-orchestrator-service
  namespace: claude-orchestrator
spec:
  selector:
    app: claude-orchestrator
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: LoadBalancer

---
# kubernetes/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: claude-orchestrator-ingress
  namespace: claude-orchestrator
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: orchestrator.company.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: claude-orchestrator-service
            port:
              number: 80
```

Deploy to Kubernetes:
```bash
kubectl apply -f kubernetes/
```

#### Helm Chart Deployment

```bash
# Add Helm repository
helm repo add claude-orchestrator https://anthropic.github.io/claude-code-subagents-orchestrator/

# Install with custom values
helm install my-orchestrator claude-orchestrator/claude-orchestrator \
  --set replicaCount=3 \
  --set image.tag=latest \
  --set service.type=LoadBalancer
```

## Cloud Platform Deployments

### AWS Deployment

#### EC2 with Auto Scaling

```bash
# User data script for EC2 instances
#!/bin/bash
yum update -y
curl -sL https://rpm.nodesource.com/setup_18.x | bash -
yum install -y nodejs

npm install -g claude-code-subagents-orchestrator

# Configure as systemd service
systemctl enable claude-orchestrator
systemctl start claude-orchestrator
```

#### ECS Deployment

```json
{
  "family": "claude-orchestrator",
  "taskRoleArn": "arn:aws:iam::account:role/ecsTaskRole",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "orchestrator",
      "image": "ghcr.io/anthropic/claude-code-subagents-orchestrator:latest",
      "portMappings": [
        {
          "containerPort": 3000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {"name": "NODE_ENV", "value": "production"},
        {"name": "LOG_LEVEL", "value": "info"}
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/claude-orchestrator",
          "awslogs-region": "us-west-2",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}
```

#### EKS Deployment

```bash
# Create EKS cluster
eksctl create cluster --name claude-orchestrator --region us-west-2

# Deploy using kubectl
kubectl apply -f kubernetes/

# Configure ingress with ALB
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.4.0/docs/install/iam_policy.json
```

### Google Cloud Platform

#### Cloud Run Deployment

```bash
# Build and deploy to Cloud Run
gcloud run deploy claude-orchestrator \
  --image ghcr.io/anthropic/claude-code-subagents-orchestrator:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --port 3000 \
  --memory 1Gi \
  --cpu 1 \
  --min-instances 1 \
  --max-instances 10
```

#### GKE Deployment

```bash
# Create GKE cluster
gcloud container clusters create claude-orchestrator \
  --zone us-central1-a \
  --num-nodes 3 \
  --enable-autoscaling \
  --min-nodes 1 \
  --max-nodes 10

# Deploy application
kubectl apply -f kubernetes/
```

### Azure Deployment

#### Container Instances

```bash
# Deploy to Azure Container Instances
az container create \
  --resource-group myResourceGroup \
  --name claude-orchestrator \
  --image ghcr.io/anthropic/claude-code-subagents-orchestrator:latest \
  --dns-name-label claude-orchestrator \
  --ports 3000 \
  --environment-variables NODE_ENV=production LOG_LEVEL=info
```

#### AKS Deployment

```bash
# Create AKS cluster
az aks create \
  --resource-group myResourceGroup \
  --name claude-orchestrator \
  --node-count 3 \
  --enable-addons monitoring \
  --generate-ssh-keys

# Deploy application
kubectl apply -f kubernetes/
```

## Configuration Management

### Environment Variables

```bash
# Production environment variables
NODE_ENV=production
LOG_LEVEL=info
PORT=3000

# Security settings
JWT_SECRET=your-secret-key
ENCRYPTION_KEY=your-encryption-key

# Database settings (if applicable)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=orchestrator
DB_USER=orchestrator
DB_PASSWORD=secure-password

# Cache settings
REDIS_URL=redis://localhost:6379
CACHE_TTL=3600

# Monitoring
PROMETHEUS_ENDPOINT=/metrics
HEALTH_CHECK_ENDPOINT=/health
```

### Configuration Files

```yaml
# config/production.yml
server:
  port: 3000
  host: 0.0.0.0
  
logging:
  level: info
  format: json
  
agents:
  max_concurrent: 10
  timeout: 30000
  
cache:
  enabled: true
  ttl: 3600
  
security:
  cors:
    enabled: true
    origins: ["https://claude.ai"]
  rate_limit:
    enabled: true
    max_requests: 100
    window: 60000
```

## Monitoring and Logging

### Metrics Collection

```yaml
# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'claude-orchestrator'
    static_configs:
      - targets: ['orchestrator:3000']
    metrics_path: '/metrics'
```

### Log Aggregation

```yaml
# docker-compose.logging.yml
version: '3.8'

services:
  orchestrator:
    logging:
      driver: "fluentd"
      options:
        fluentd-address: localhost:24224
        tag: orchestrator

  fluentd:
    image: fluent/fluentd:v1.14-1
    volumes:
      - ./fluentd/conf:/fluentd/etc
    ports:
      - "24224:24224"
```

### Health Checks

```bash
# Custom health check script
#!/bin/bash
response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/health)
if [ $response -eq 200 ]; then
  exit 0
else
  exit 1
fi
```

## Security Configuration

### SSL/TLS Setup

```nginx
# nginx SSL configuration
server {
    listen 443 ssl http2;
    server_name orchestrator.company.com;
    
    ssl_certificate /etc/ssl/certs/orchestrator.crt;
    ssl_certificate_key /etc/ssl/private/orchestrator.key;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    ssl_prefer_server_ciphers off;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Firewall Configuration

```bash
# UFW configuration
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```

## Backup and Recovery

### Data Backup

```bash
#!/bin/bash
# backup-script.sh

BACKUP_DIR="/backup/claude-orchestrator"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR/$DATE

# Backup application data
docker run --rm -v orchestrator_data:/data -v $BACKUP_DIR/$DATE:/backup alpine \
  tar czf /backup/data.tar.gz /data

# Backup configuration
cp -r /opt/claude-orchestrator/config $BACKUP_DIR/$DATE/

# Backup database (if applicable)
pg_dump orchestrator > $BACKUP_DIR/$DATE/database.sql

# Clean old backups (keep last 7 days)
find $BACKUP_DIR -type d -mtime +7 -exec rm -rf {} \;
```

### Disaster Recovery

```bash
#!/bin/bash
# restore-script.sh

BACKUP_DIR="/backup/claude-orchestrator"
RESTORE_DATE=$1

if [ -z "$RESTORE_DATE" ]; then
  echo "Usage: $0 <backup_date>"
  exit 1
fi

# Stop services
systemctl stop claude-orchestrator

# Restore data
tar xzf $BACKUP_DIR/$RESTORE_DATE/data.tar.gz -C /

# Restore configuration
cp -r $BACKUP_DIR/$RESTORE_DATE/config/* /opt/claude-orchestrator/config/

# Restore database (if applicable)
psql orchestrator < $BACKUP_DIR/$RESTORE_DATE/database.sql

# Start services
systemctl start claude-orchestrator
```

## Performance Optimization

### Resource Tuning

```bash
# Node.js performance tuning
export NODE_OPTIONS="--max-old-space-size=2048 --enable-source-maps"

# System tuning
echo 'net.core.somaxconn = 1024' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_max_syn_backlog = 1024' >> /etc/sysctl.conf
sysctl -p
```

### Caching Configuration

```yaml
# Redis configuration
redis:
  host: localhost
  port: 6379
  password: secure-password
  db: 0
  keyPrefix: 'orchestrator:'
  ttl: 3600
```

## Maintenance

### Update Procedures

```bash
#!/bin/bash
# update-script.sh

# Backup current version
./backup-script.sh

# Pull latest image
docker pull ghcr.io/anthropic/claude-code-subagents-orchestrator:latest

# Update with zero downtime
docker-compose up -d --no-deps orchestrator

# Run health checks
sleep 30
./health-check.sh

# Clean old images
docker image prune -f
```

### Regular Maintenance Tasks

```bash
# Weekly maintenance cron job
0 2 * * 0 /opt/scripts/weekly-maintenance.sh

#!/bin/bash
# weekly-maintenance.sh

# Update system packages
apt update && apt upgrade -y

# Clean logs older than 30 days
find /var/log/claude-orchestrator -name "*.log" -mtime +30 -delete

# Vacuum database (if applicable)
psql orchestrator -c "VACUUM ANALYZE;"

# Restart services
systemctl restart claude-orchestrator

# Run health check
claude-orchestrator health-check
```

## Troubleshooting Deployments

### Common Deployment Issues

1. **Port conflicts**: Check for conflicting services
2. **Permission issues**: Verify user permissions and file ownership
3. **Resource limits**: Monitor CPU and memory usage
4. **Network connectivity**: Test internal and external connections
5. **Configuration errors**: Validate configuration files

### Debugging Tools

```bash
# Check service status
systemctl status claude-orchestrator

# View logs
journalctl -u claude-orchestrator -f

# Monitor resources
htop
iotop

# Network debugging
netstat -tulpn | grep 3000
tcpdump -i any port 3000
```

### Recovery Procedures

```bash
# Emergency recovery steps
1. Stop the service
2. Restore from last known good backup
3. Check configuration
4. Start service
5. Verify functionality
6. Monitor for issues
```

This deployment guide provides comprehensive coverage of production deployment scenarios. For specific environments or custom requirements, consult the detailed troubleshooting guide and consider engaging with professional services for enterprise deployments.