Documentation files
This commit is contained in:
rafaeldpsilva
422
documents/DEPLOYMENT_GUIDE.md
Normal file
422
documents/DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 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
|
||||
|
||||
### Prerequisites
|
||||
- Docker 20.0+
|
||||
- Docker Compose 2.0+
|
||||
- 8GB RAM minimum
|
||||
- 10GB free disk space
|
||||
|
||||
### 1. Deploy the Complete System
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
./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**:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
# Check Docker status
|
||||
docker ps
|
||||
|
||||
# Check logs
|
||||
./deploy.sh logs
|
||||
|
||||
# Restart problematic service
|
||||
docker-compose restart battery-service
|
||||
```
|
||||
|
||||
**Database connection issues**:
|
||||
```bash
|
||||
# Check MongoDB status
|
||||
docker-compose logs mongodb
|
||||
|
||||
# Restart database
|
||||
docker-compose restart mongodb
|
||||
|
||||
# Wait for services to reconnect (30 seconds)
|
||||
```
|
||||
|
||||
**Authentication failures**:
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Backup databases
|
||||
docker exec energy-mongodb mongodump --out /data/backup
|
||||
|
||||
# Restore databases
|
||||
docker exec energy-mongodb mongorestore /data/backup
|
||||
```
|
||||
|
||||
### Clean Deployment
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user