cube-ms/templates/api/DEPLOYMENT.md

Production-ready microservice framework with health monitoring, validation, error handling, and Docker Swarm support

# 🚀 Cube-MS Deployment Guide

Complete deployment guide for running Cube-MS in development and production environments.

## 📋 Prerequisites

### Required Software
- **Node.js 18+** (for local development)
- **Docker 20.0+** (for containerization)
- **Docker Compose 3.8+** (for multi-container setup)
- **MongoDB 6.0+** (if running without Docker)

### Optional Tools
- **cube-ms CLI** (recommended)
- **Git** (for version control)
- **curl** or **Postman** (for API testing)

## 🏗️ Project Setup

### 1. Create New Project

Using Cube-MS CLI (recommended):
```bash
# Install CLI globally
npm install -g cube-ms

# Create new project
cube-ms create my-app --template basic
cd my-app
```

### 2. Environment Configuration

Copy and configure environment files:
```bash
# For local development
cp .env.example .env

# For Docker deployment
cp .env.docker .env
```

**⚠️ IMPORTANT**: Change all default passwords and secrets!

### 3. Required Environment Variables

**Minimum required variables for Cube-MS to run:**

```bash
# Application (REQUIRED)
NODE_ENV=development
PORT=3000
APP_NAME=MyCubeMSApp
SERVICE_NAME=my-service

# Database (REQUIRED)
MONGODB_URL=mongodb://localhost:27017/my-app
LOG_DB_URL=mongodb://localhost:27017/my-app-logs

# Security (REQUIRED)
SECURITY_ENABLED=true
JWT_SECRET=your-super-secret-jwt-key
MASTER_API_KEY=your-master-api-key

# Features (REQUIRED)
RATE_LIMIT_ENABLED=true
MONITORING_ENABLED=true
HEALTH_CHECK_ENABLED=true
```

## 🔧 Development Setup

### Local Development (Without Docker)

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Start MongoDB locally:**
   ```bash
   # Using Docker
   docker run -d --name mongodb -p 27017:27017 mongo:6
   
   # Or install MongoDB locally
   # https://docs.mongodb.com/manual/installation/
   ```

3. **Start development server:**
   ```bash
   npm run dev
   # or
   cube-ms dev
   ```

4. **Verify installation:**
   ```bash
   curl http://localhost:3000/health
   ```

### Docker Development Setup

1. **Start development environment:**
   ```bash
   # With database UI tools
   docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
   
   # Or use profile
   docker-compose --profile dev up
   ```

2. **Access services:**
   - **App**: http://localhost:3000
   - **MongoDB UI**: http://localhost:8081
   - **Redis UI**: http://localhost:8082

## 🚀 Production Deployment

### Docker Production Deployment

1. **Prepare environment:**
   ```bash
   # Copy and edit production environment
   cp .env.docker .env
   
   # CHANGE ALL PASSWORDS AND SECRETS!
   vim .env
   ```

2. **Build and deploy:**
   ```bash
   # Basic production deployment
   docker-compose up -d
   
   # With load balancer
   docker-compose --profile production up -d
   
   # With monitoring
   docker-compose --profile production --profile monitoring up -d
   ```

3. **Verify deployment:**
   ```bash
   # Check service health
   curl http://localhost:3000/health
   
   # Check containers
   docker-compose ps
   
   # View logs
   docker-compose logs -f app
   ```

### Docker Swarm Deployment

1. **Initialize Docker Swarm:**
   ```bash
   docker swarm init
   ```

2. **Create production compose file:**
   ```bash
   # docker-compose.prod.yml
   version: '3.8'
   
   services:
     app:
       image: cube-ms-app:latest
       deploy:
         replicas: 3
         restart_policy:
           condition: on-failure
           max_attempts: 3
         resources:
           limits:
             cpus: '1.0'
             memory: 512M
   ```

3. **Deploy stack:**
   ```bash
   docker stack deploy -c docker-compose.yml -c docker-compose.prod.yml cube-ms-stack
   ```

## 🐳 Docker Commands Reference

### Development Commands
```bash
# Start development environment
docker-compose --profile dev up

# Rebuild and start
docker-compose --profile dev up --build

# View logs
docker-compose logs -f app

# Execute command in container
docker-compose exec app npm run test

# Stop all services
docker-compose down
```

### Production Commands
```bash
# Deploy production
docker-compose --profile production up -d

# Scale application
docker-compose up --scale app=3 -d

# Update application
docker-compose pull app
docker-compose up -d app

# Backup database
docker-compose exec mongodb mongodump --out /data/backup/
```

### Monitoring Commands
```bash
# Start with monitoring
docker-compose --profile monitoring up -d

# View Prometheus metrics
curl http://localhost:9090/api/v1/query?query=up

# Access Grafana
open http://localhost:3001
```

## 🌐 Service Endpoints

### Application Endpoints
- **API Root**: `GET /`
- **Health Check**: `GET /health`
- **Liveness Probe**: `GET /health/live`
- **Readiness Probe**: `GET /health/ready`
- **API Documentation**: `GET /api`

### Management Endpoints (Development)
- **MongoDB UI**: http://localhost:8081 (`admin:admin123`)
- **Redis UI**: http://localhost:8082
- **Prometheus**: http://localhost:9090
- **Grafana**: http://localhost:3001 (`admin:admin123`)

## 🔒 Security Configuration

### Production Security Checklist

- [ ] **Change all default passwords**
- [ ] **Generate strong JWT secret** (min 32 chars)
- [ ] **Configure CORS origins** (remove `*`)
- [ ] **Enable HTTPS/SSL**
- [ ] **Set up firewall rules**
- [ ] **Configure rate limiting**
- [ ] **Enable security headers**
- [ ] **Set up monitoring alerts**

### Environment-Specific Security

**Development:**
```bash
SECURITY_LEVEL=lenient
CORS_ORIGIN=*
JWT_SECRET=dev-secret-change-in-production
```

**Production:**
```bash
SECURITY_LEVEL=strict
CORS_ORIGIN=https://yourdomain.com
JWT_SECRET=super-strong-secret-key-min-32-chars-random
```

## 📊 Monitoring & Observability

### Health Monitoring

Built-in health checks are available:
```bash
# Overall health
curl http://localhost:3000/health

# Kubernetes liveness
curl http://localhost:3000/health/live

# Kubernetes readiness  
curl http://localhost:3000/health/ready

# Detailed health info
curl http://localhost:3000/health/detailed
```

### Performance Monitoring

Enable performance monitoring:
```bash
MONITORING_ENABLED=true
METRICS_INTERVAL=10000
MEMORY_WARNING_MB=256
CPU_WARNING_THRESHOLD=80
```

### Log Monitoring

Logs are automatically stored in MongoDB:
```bash
# View application logs
docker-compose logs -f app

# View MongoDB logs
docker-compose logs -f mongodb

# Access logs via MongoDB
db.logs.find().sort({timestamp: -1}).limit(10)
```

## 🔧 Troubleshooting

### Common Issues

1. **Port already in use**
   ```bash
   # Change port in .env file
   PORT=8080
   ```

2. **MongoDB connection failed**
   ```bash
   # Check MongoDB is running
   docker-compose ps mongodb
   
   # Check connection string
   MONGODB_URL=mongodb://mongodb:27017/cube-ms
   ```

3. **Permission denied errors**
   ```bash
   # Fix Docker permissions
   sudo chown -R $USER:$USER .
   ```

4. **Out of memory**
   ```bash
   # Increase container limits
   docker-compose up --scale app=1 --memory=1G
   ```

### Debug Mode

Enable debug mode for troubleshooting:
```bash
DEBUG_MODE=true
LOG_LEVEL=debug
DEV_ERROR_HANDLER=true
DEV_STACK_TRACES=true
```

### Performance Issues

1. **High memory usage**
   ```bash
   # Enable garbage collection
   GC_ENABLED=true
   MEMORY_WARNING_MB=256
   ```

2. **Slow response times**
   ```bash
   # Check database connections
   DB_MAX_POOL_SIZE=10
   
   # Enable monitoring
   MONITORING_ENABLED=true
   ```

## 📈 Scaling & Performance

### Horizontal Scaling

```bash
# Scale with Docker Compose
docker-compose up --scale app=3 -d

# Scale with Docker Swarm
docker service scale cube-ms-stack_app=5
```

### Performance Tuning

```bash
# Database optimization
DB_MAX_POOL_SIZE=20
DB_MIN_POOL_SIZE=5

# Memory optimization  
MEMORY_WARNING_MB=512
GC_ENABLED=true

# Request optimization
REQUEST_TIMEOUT=15000
BODY_LIMIT=5mb
```

### Load Testing

```bash
# Install load testing tool
npm install -g artillery

# Run load test
artillery quick --count 100 --num 10 http://localhost:3000/health
```

## 🔄 CI/CD Integration

### GitHub Actions Example

```yaml
name: Deploy Cube-MS

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Build Docker image
        run: docker build -t cube-ms-app:latest .
        
      - name: Deploy to production
        run: |
          docker-compose --profile production up -d
          docker-compose exec app npm run test
```

### Health Check Integration

```bash
# Add to CI/CD pipeline
curl -f http://localhost:3000/health/live || exit 1
```

## 📞 Support & Resources

- **Documentation**: [README.md](./README.md)
- **CLI Guide**: [CLI.md](../CLI.md)
- **API Examples**: [Examples/](../Examples/)
- **Issues**: Create GitHub issue
- **Security**: Follow security best practices

---

**🎯 Quick Start Summary:**
1. `cube-ms create my-app`
2. `cd my-app && cp .env.docker .env`
3. Edit `.env` - change passwords!
4. `docker-compose --profile dev up`
5. Open http://localhost:3000/health ✅