sac4cps-backend/documents/DEPLOYMENT_GUIDE.md

Energy Management Microservices Deployment Guide

This guide provides comprehensive instructions for deploying and managing the Energy Management microservices architecture based on the tiocps/iot-building-monitoring system.

🏗️ Architecture Overview

The system consists of 6 independent microservices coordinated by an API Gateway:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client Apps   │    │   Web Dashboard │    │   Mobile App    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
         ┌─────────────────────────────────────────────────────┐
         │              API Gateway (Port 8000)                │
         │            • Request routing                        │
         │            • Authentication                         │
         │            • Load balancing                         │
         │            • Rate limiting                          │
         └─────────────────────────────────────────────────────┘
                                 │
     ┌───────────────────────────┼───────────────────────────┐
     │                           │                           │
┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│ Token   │  │ Battery │  │ Demand  │  │   P2P   │  │Forecast │  │   IoT   │
│Service  │  │Service  │  │Response │  │Trading  │  │Service  │  │Control  │
│  8001   │  │  8002   │  │  8003   │  │  8004   │  │  8005   │  │  8006   │
└─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘
     │            │            │            │            │            │
     └────────────┼────────────┼────────────┼────────────┼────────────┘
                  │            │            │            │
     ┌─────────────────────────────────────────────────────────────────┐
     │                    Shared Infrastructure                        │
     │  ┌─────────────┐              ┌─────────────┐                   │
     │  │  MongoDB    │              │    Redis    │                   │
     │  │   :27017    │              │    :6379    │                   │
     │  │ • Data      │              │ • Caching   │                   │
     │  │ • Metadata  │              │ • Events    │                   │
     │  └─────────────┘              └─────────────┘                   │
     └─────────────────────────────────────────────────────────────────┘

🚀 Quick Start

1. Deploy the Complete System

cd microservices/
./deploy.sh deploy

This command will:

• ✅ Check dependencies
• ✅ Set up environment
• ✅ Build all services
• ✅ Start infrastructure (MongoDB, Redis)
• ✅ Start all microservices
• ✅ Configure networking
• ✅ Run health checks

2. Verify Deployment

./deploy.sh status

Expected output:

[SUCCESS] api-gateway is healthy
[SUCCESS] token-service is healthy
[SUCCESS] battery-service is healthy
[SUCCESS] demand-response-service is healthy
[SUCCESS] p2p-trading-service is healthy
[SUCCESS] forecasting-service is healthy
[SUCCESS] iot-control-service is healthy

3. Access the System

• API Gateway: http://localhost:8000
• System Health: http://localhost:8000/health
• Service Status: http://localhost:8000/services/status
• System Overview: http://localhost:8000/api/v1/overview

📋 Service Details

🔐 Token Service (Port 8001)

Purpose: JWT authentication and authorization Database: energy_dashboard_tokens

Key Endpoints:

# Generate token
curl -X POST "http://localhost:8001/tokens/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "admin_user",
    "list_of_resources": ["batteries", "demand_response", "p2p", "forecasting", "iot"],
    "data_aggregation": true,
    "time_aggregation": true,
    "exp_hours": 24
  }'

# Validate token
curl -X POST "http://localhost:8001/tokens/validate" \
  -H "Content-Type: application/json" \
  -d '{"token": "your_jwt_token_here"}'

🔋 Battery Service (Port 8002)

Purpose: Energy storage management and optimization Database: energy_dashboard_batteries

Key Features:

• Battery monitoring and status tracking
• Charging/discharging control
• Health monitoring and maintenance alerts
• Energy storage optimization
• Performance analytics

Example Usage:

# Get all batteries
curl "http://localhost:8002/batteries" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Charge a battery
curl -X POST "http://localhost:8002/batteries/BATT001/charge" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "power_kw": 50.0,
    "duration_minutes": 120
  }'

# Get battery analytics
curl "http://localhost:8002/batteries/analytics/summary" \
  -H "Authorization: Bearer YOUR_TOKEN"

⚡ Demand Response Service (Port 8003)

Purpose: Grid interaction and load management Database: energy_dashboard_demand_response

Key Features:

• Demand response event management
• Load reduction coordination
• Flexibility forecasting
• Auto-response configuration
• Performance analytics

Example Usage:

# Send demand response invitation
curl -X POST "http://localhost:8003/invitations/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_time": "2025-01-10T14:00:00Z",
    "load_kwh": 100,
    "load_percentage": 15,
    "duration_minutes": 60,
    "iots": ["DEVICE001", "DEVICE002"]
  }'

# Get current flexibility
curl "http://localhost:8003/flexibility/current" \
  -H "Authorization: Bearer YOUR_TOKEN"

🤝 P2P Trading Service (Port 8004)

Purpose: Peer-to-peer energy marketplace Database: energy_dashboard_p2p

Key Features:

• Energy trading marketplace
• Bid/ask management
• Transaction processing
• Price optimization
• Market analytics

📊 Forecasting Service (Port 8005)

Purpose: ML-based energy forecasting Database: energy_dashboard_forecasting

Key Features:

• Consumption forecasting
• Generation forecasting
• Flexibility forecasting
• Historical data analysis
• Model training and optimization

🏠 IoT Control Service (Port 8006)

Purpose: IoT device management and control Database: energy_dashboard_iot

Key Features:

• Device registration and management
• Remote device control
• Automation rules
• Device status monitoring
• Integration with other services

🛠️ Management Commands

Service Management

# Start all services
./deploy.sh start

# Stop all services
./deploy.sh stop

# Restart all services
./deploy.sh restart

# View service status
./deploy.sh status

Logs and Debugging

# View all logs
./deploy.sh logs

# View specific service logs
./deploy.sh logs battery-service
./deploy.sh logs api-gateway

# Follow logs in real-time
docker-compose logs -f token-service

Scaling Services

# Scale a specific service
docker-compose up -d --scale battery-service=3

# Scale multiple services
docker-compose up -d \
  --scale battery-service=2 \
  --scale demand-response-service=2

🔧 Configuration

Environment Variables

Each service can be configured using environment variables:

Common Variables:

• MONGO_URL: MongoDB connection string
• REDIS_URL: Redis connection string
• LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)

Service-Specific Variables:

• JWT_SECRET_KEY: Token service secret key
• TOKEN_SERVICE_URL: API Gateway token service URL
• BATTERY_SERVICE_URL: Battery service URL for IoT control

Database Configuration

MongoDB databases are automatically created:

• energy_dashboard_tokens: Token management
• energy_dashboard_batteries: Battery data
• energy_dashboard_demand_response: DR events
• energy_dashboard_p2p: P2P transactions
• energy_dashboard_forecasting: Forecasting data
• energy_dashboard_iot: IoT device data

🔐 Security

Authentication Flow

1. Client requests token from Token Service
2. Token Service validates credentials and issues JWT
3. Client includes JWT in Authorization header
4. API Gateway validates token with Token Service
5. Request forwarded to target microservice

Token Permissions

Tokens include resource-based permissions:

{
  "name": "user_name",
  "list_of_resources": ["batteries", "demand_response"],
  "data_aggregation": true,
  "time_aggregation": false,
  "embargo": 0,
  "exp": 1736524800
}

📊 Monitoring

Health Checks

All services provide health endpoints:

# API Gateway health (includes all services)
curl http://localhost:8000/health

# Individual service health
curl http://localhost:8001/health  # Token Service
curl http://localhost:8002/health  # Battery Service
curl http://localhost:8003/health  # Demand Response Service

Metrics and Analytics

• Gateway Stats: Request counts, success rates, uptime
• Battery Analytics: Energy flows, efficiency, health
• DR Performance: Event success rates, load reduction
• P2P Metrics: Trading volumes, prices, participants

🚨 Troubleshooting

Common Issues

Services won't start:

# Check Docker status
docker ps

# Check logs
./deploy.sh logs

# Restart problematic service
docker-compose restart battery-service

Database connection issues:

# Check MongoDB status
docker-compose logs mongodb

# Restart database
docker-compose restart mongodb

# Wait for services to reconnect (30 seconds)

Authentication failures:

# Check token service
curl http://localhost:8001/health

# Verify token generation
curl -X POST "http://localhost:8001/tokens/generate" \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "list_of_resources": ["test"]}'

Performance Optimization

• Increase service replicas for high load
• Monitor memory usage and adjust limits
• Use Redis for caching frequently accessed data
• Implement database indexes for query optimization

🔄 Updates and Maintenance

Service Updates

# Update specific service
docker-compose build battery-service
docker-compose up -d battery-service

# Update all services
./deploy.sh build
./deploy.sh restart

Database Maintenance

# Backup databases
docker exec energy-mongodb mongodump --out /data/backup

# Restore databases
docker exec energy-mongodb mongorestore /data/backup

Clean Deployment

# Complete system cleanup
./deploy.sh cleanup

# Fresh deployment
./deploy.sh deploy

📈 Scaling and Production

Production Considerations

1. Security: Change default passwords and secrets
2. SSL/TLS: Configure HTTPS with proper certificates
3. Monitoring: Set up Prometheus and Grafana
4. Logging: Configure centralized logging
5. Backup: Implement automated database backups
6. Resource Limits: Set appropriate CPU and memory limits

Kubernetes Deployment

The microservices can be deployed to Kubernetes:

# Generate Kubernetes manifests
kompose convert

# Deploy to Kubernetes
kubectl apply -f kubernetes/

🆘 Support

Documentation

• API documentation: http://localhost:8000/docs
• Service-specific docs: http://localhost:800X/docs (where X = service port)

Logs Location

• Container logs: docker-compose logs [service]
• Application logs: Check service-specific log files
• Gateway logs: Include request routing and authentication

This microservices implementation provides a robust, scalable foundation for energy management systems with independent deployability, comprehensive monitoring, and production-ready features.