Documentation > Deployment Guide

Deployment Guide

Deploy Neo N3 MCP Server to production with Docker, monitoring, and best practices

🚀 Deployment Options

Choose the deployment method that best fits your infrastructure and requirements.

🐳

Docker Deployment

Containerized deployment with all dependencies included. Perfect for cloud environments and scalable architectures.

  • Isolated environment
  • Easy scaling
  • Consistent deployments
  • Built-in health checks
☁️

Cloud Deployment

Deploy to major cloud providers with managed services, auto-scaling, and high availability.

  • AWS, GCP, Azure support
  • Auto-scaling
  • Load balancing
  • Managed infrastructure
⚙️

Kubernetes

Enterprise-grade orchestration with advanced scaling, rolling updates, and service mesh integration.

  • Horizontal scaling
  • Rolling updates
  • Service discovery
  • Resource management

🐳 Docker Deployment

Basic Docker Setup

Dockerfile 
# Production Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .

# Security updates
RUN apk update && apk upgrade && \
    apk add --no-cache dumb-init && \
    rm -rf /var/cache/apk/*

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Set permissions
RUN chown -R nodejs:nodejs /app
USER nodejs

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

EXPOSE 3000
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "dist/index.js"]

Docker Compose Production Setup

docker-compose.prod.yml 
version: '3.8'

services:
  neo-mcp:
    image: r3e/neo-n3-mcp:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - NEO_NETWORK=mainnet
      - LOG_LEVEL=info
      - ENABLE_METRICS=true
      - RATE_LIMIT_ENABLED=true
    volumes:
      - ./logs:/app/logs
      - ./config:/app/config:ro
    networks:
      - neo-network
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

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

  prometheus:
    image: prom/prometheus:latest
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    networks:
      - neo-network

networks:
  neo-network:
    driver: bridge
💡 Production Tips
  • Always use specific image tags, never latest in production
  • Set resource limits to prevent container from consuming all system resources
  • Use health checks for automatic recovery
  • Mount logs and config as volumes for persistence

☁️ Cloud Deployment

AWS Deployment with ECS

aws-ecs-task.json 
{
  "family": "neo-n3-mcp",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::ACCOUNT:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::ACCOUNT:role/neo-mcp-task-role",
  "containerDefinitions": [
    {
      "name": "neo-mcp",
      "image": "r3e/neo-n3-mcp:v1.0.0",
      "portMappings": [
        {
          "containerPort": 3000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {"name": "NODE_ENV", "value": "production"},
        {"name": "NEO_NETWORK", "value": "mainnet"},
        {"name": "LOG_LEVEL", "value": "info"}
      ],
      "secrets": [
        {
          "name": "API_SECRET",
          "valueFrom": "arn:aws:ssm:region:account:parameter/neo-mcp/api-secret"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/neo-n3-mcp",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "healthCheck": {
        "command": ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 60
      }
    }
  ]
}

📊 Monitoring & Observability

Health Checks

Health Check Endpoint 
# Health check endpoint
curl http://localhost:3000/health

# Expected response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": 3600,
  "checks": {
    "neo_rpc": {
      "status": "healthy",
      "latency": 45,
      "last_check": "2024-01-15T10:29:55Z"
    },
    "memory": {
      "status": "healthy",
      "usage_mb": 256,
      "limit_mb": 512
    },
    "database": {
      "status": "healthy",
      "connection": "active"
    }
  }
}

Prometheus Metrics

prometheus.yml 
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'neo-n3-mcp'
    static_configs:
      - targets: ['neo-mcp:3000']
    metrics_path: '/metrics'
    scrape_interval: 30s
    scrape_timeout: 10s

  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']

rule_files:
  - "alert_rules.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets:
          - alertmanager:9093
✅ Key Metrics to Monitor
  • Request Rate: RPS and response times
  • Error Rate: 4xx/5xx responses
  • Resource Usage: CPU, memory, disk
  • Neo RPC Health: Connection status and latency
  • Tool Execution: Success rates and performance

🔒 Security Best Practices

⚠️ Security Checklist
  • Never expose private keys in environment variables or logs
  • Use HTTPS/TLS for all external communications
  • Enable rate limiting to prevent abuse
  • Regularly update Docker images and dependencies
  • Use secrets management for sensitive configuration
  • Implement proper access controls and authentication
  • Monitor for security vulnerabilities

Nginx SSL Configuration

nginx.conf 
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    ssl_prefer_server_ciphers off;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    
    # Rate limiting
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req zone=api burst=20 nodelay;
    
    location / {
        proxy_pass http://neo-mcp: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;
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}