417 lines
13 KiB
Markdown
417 lines
13 KiB
Markdown
# 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
|
|
```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.
|