MMCP Trade Twins - Production Deployment Guide

🚀 Production Infrastructure

This repository contains the complete production-ready infrastructure for the MMCP Trade Twins project, including CI/CD pipelines, containerization, and cloud deployment configurations.

📋 Table of Contents

• Quick Start
• Infrastructure Overview
• Deployment
• Environment Configuration
• Monitoring & Observability
• Security
• Scaling
• Backup & Recovery

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Git
• Access to cloud provider (AWS, GCP, or Azure)
• Domain name (for production)

Local Development

# Clone the repository
git clone https://github.com/ChainMailGlobal/Nebius.Build.git
cd Nebius.Build

# Set up environment
cp .env.template .env
# Edit .env with your local configuration

# Start development environment
docker-compose up -d

# Run database migrations
docker-compose exec backend python migrate.py

# Access the application
# Backend API: http://localhost:8000
# Frontend: http://localhost:3000

Production Deployment

1. Configure Environment Variables

   cp .env.production .env
   # Edit .env with your production configuration

2. Deploy to Cloud

   # Using Docker Compose
   docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
   
   # Or using Kubernetes (see k8s/ directory)
   kubectl apply -f k8s/

🏗️ Infrastructure Overview

Architecture Components

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Load Balancer │    │     Nginx       │    │   Monitoring    │
│   (Cloudflare)  │───▶│   (Reverse      │───▶│   (Prometheus)  │
│                 │    │    Proxy)       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend API   │    │   Redis Cache   │
│   (React)       │    │   (FastAPI)     │    │   (Caching)     │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PostgreSQL    │    │   Supabase      │    │   Object Store  │
│   (pgvector)    │    │   (Vector DB)   │    │   (S3/MinIO)    │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Services

• Backend API: FastAPI application with AI integration
• Frontend: React application with TypeScript
• Database: PostgreSQL with pgvector extension
• Cache: Redis for session storage and caching
• Reverse Proxy: Nginx with SSL termination
• Monitoring: Prometheus and Grafana
• Logging: Centralized logging with structured format

🚀 Deployment

Option 1: Docker Compose (Recommended for Small-Medium Scale)

# Production deployment
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# View logs
docker-compose logs -f

# Scale services
docker-compose up -d --scale backend=3

Option 2: Kubernetes (Recommended for Large Scale)

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Monitor deployment
kubectl get pods -w

# Scale deployments
kubectl scale deployment mmcp-backend --replicas=5

Option 3: Cloud Provider Specific

AWS ECS

# Build and push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com
docker build -t mmcp-trade-twins .
docker tag mmcp-trade-twins:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/mmcp-trade-twins:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/mmcp-trade-twins:latest

Google Cloud Run

# Build and deploy
gcloud builds submit --tag gcr.io/<project-id>/mmcp-trade-twins
gcloud run deploy mmcp-trade-twins --image gcr.io/<project-id>/mmcp-trade-twins --platform managed

Azure Container Instances

# Build and deploy
az acr login --name <registry-name>
docker build -t <registry-name>.azurecr.io/mmcp-trade-twins .
docker push <registry-name>.azurecr.io/mmcp-trade-twins
az container create --resource-group <resource-group> --name mmcp-trade-twins --image <registry-name>.azurecr.io/mmcp-trade-twins

🔧 Environment Configuration

Environment Files

• .env.template - Development environment template
• .env.production - Production environment template
• .env.staging - Staging environment template

Required Environment Variables

# Database
DATABASE_URL="postgresql://user:password@host:port/database"
REDIS_URL="redis://host:port"

# AI Services
NEBUIUS_API_KEY="your-nebuis-api-key"
TAVILY_API_KEY="your-tavily-api-key"
TOLOKA_API_KEY="your-toloka-api-key"

# Blockchain
SCROLL_PRIVATE_KEY="your-scroll-private-key"
SCROLL_RPC_URL="https://scroll-mainnet.chainstacklabs.com"

# Security
JWT_SECRET_KEY="your-jwt-secret-key"
SENTRY_DSN="your-sentry-dsn"

# Cloud Storage
AWS_ACCESS_KEY_ID="your-aws-access-key"
AWS_SECRET_ACCESS_KEY="your-aws-secret-key"
AWS_S3_BUCKET="your-s3-bucket"

Secrets Management

For production deployments, use your cloud provider's secrets management:

• AWS: AWS Secrets Manager or Parameter Store
• GCP: Secret Manager
• Azure: Key Vault
• Kubernetes: Secrets or External Secrets Operator

📊 Monitoring & Observability

Health Checks

• Application Health: GET /health
• Database Health: GET /health/db
• Redis Health: GET /health/redis
• External Services: GET /health/external

Metrics

• Application Metrics: Prometheus endpoint at /metrics
• Custom Metrics: Agent performance, marble quality, constitutional compliance
• Infrastructure Metrics: CPU, memory, disk, network

Logging

• Structured Logging: JSON format with correlation IDs
• Log Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
• Log Aggregation: ELK Stack or cloud-native solutions

Alerting

• Critical Alerts: Application downtime, database failures
• Warning Alerts: High error rates, performance degradation
• Info Alerts: Deployment notifications, scaling events

🔒 Security

Network Security

• Firewall Rules: Restrict access to necessary ports only
• VPN Access: Use VPN for administrative access
• DDoS Protection: Enable cloud provider DDoS protection

Application Security

• Input Validation: All inputs validated and sanitized
• Authentication: JWT-based authentication with refresh tokens
• Authorization: Role-based access control (RBAC)
• Rate Limiting: API rate limiting to prevent abuse

Data Security

• Encryption at Rest: Database and file storage encryption
• Encryption in Transit: TLS/SSL for all communications
• Secrets Management: Secure storage and rotation of secrets

Compliance

• GDPR: Data protection and privacy compliance
• SOC 2: Security controls and audit trails
• PCI DSS: If handling payment information

📈 Scaling

Horizontal Scaling

• Backend: Scale FastAPI workers based on CPU/memory
• Database: Read replicas for read-heavy workloads
• Cache: Redis cluster for high availability

Vertical Scaling

• Compute: Increase instance sizes for CPU/memory intensive tasks
• Storage: Scale storage based on data growth
• Network: Increase bandwidth for high traffic

Auto-scaling Configuration

# Kubernetes HPA example
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: mmcp-backend-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: mmcp-backend
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

💾 Backup & Recovery

Database Backup

# Manual backup
pg_dump -h localhost -U mmcp_user mmcp_trade_twins > backup_$(date +%Y%m%d_%H%M%S).sql

# Automated backup (cron)
0 2 * * * pg_dump -h localhost -U mmcp_user mmcp_trade_twins | gzip > /backups/mmcp_$(date +\%F).sql.gz

Application Backup

• Code: Git repository with proper branching strategy
• Configuration: Version controlled configuration files
• Data: Regular database dumps and file system backups

Disaster Recovery

• Multi-region Deployment: Deploy to multiple regions
• Failover Strategy: Automated failover to secondary region
• Recovery Time Objective (RTO): < 1 hour
• Recovery Point Objective (RPO): < 15 minutes

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

Development Guidelines

• Follow constitutional invariant principles
• All changes must pass automated testing
• Document new features and APIs
• Maintain backward compatibility
• Use feature flags for new functionality

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Join our Discord community
• Email the development team

---

Built with ❤️ for the future of skilled trades education and automation