CalejoControl/DEPLOYMENT_GUIDE.md

Calejo Control Adapter - Deployment Guide

This guide provides comprehensive instructions for deploying the Calejo Control Adapter in on-premises customer environments.

🚀 Quick Deployment

Automated Deployment (Recommended)

For quick and easy deployment, use the automated deployment script:

# Run as root for system-wide installation
sudo ./deploy-onprem.sh

This script will:

• Check prerequisites (Docker, Docker Compose)
• Create necessary directories
• Copy all required files
• Create systemd service for automatic startup
• Build and start all services
• Create backup and health check scripts

Manual Deployment

If you prefer manual deployment:

1. Install Prerequisites

   # Install Docker
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   
   # Install Docker Compose
   sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   sudo chmod +x /usr/local/bin/docker-compose
   

2. Deploy Application

   # Create directories
   sudo mkdir -p /opt/calejo-control-adapter
   sudo mkdir -p /var/log/calejo
   sudo mkdir -p /etc/calejo
   sudo mkdir -p /var/backup/calejo
   
   # Copy files
   sudo cp -r ./* /opt/calejo-control-adapter/
   sudo cp config/settings.py /etc/calejo/
   
   # Set permissions
   sudo chmod +x /opt/calejo-control-adapter/scripts/*.sh
   
   # Build and start
   cd /opt/calejo-control-adapter
   sudo docker-compose build
   sudo docker-compose up -d
   

🧪 Testing the Deployment

End-to-End Testing

Test the complete system with mock SCADA and optimization servers:

# Run comprehensive end-to-end tests
python test-e2e-deployment.py

This will:

• Start mock SCADA server
• Start mock optimization server
• Start main application
• Test all endpoints and functionality
• Validate integration between components

Individual Component Testing

# Test mock SCADA server
python mock-scada-server.py

# Test mock optimization server
python mock-optimization-server.py

# Test local dashboard functionality
python test_dashboard_local.py

# Test deployment health
./validate-deployment.sh

🔍 Deployment Validation

After deployment, validate that everything is working correctly:

# Run comprehensive validation
./validate-deployment.sh

This checks:

• ✅ System resources (disk, memory, CPU)
• ✅ Docker container status
• ✅ Application endpoints
• ✅ Configuration validity
• ✅ Log files
• ✅ Security configuration
• ✅ Backup setup

📊 Mock Systems for Testing

Mock SCADA Server

The mock SCADA server (mock-scada-server.py) simulates:

• OPC UA Server on port 4840
• Modbus TCP Server on port 502
• Real-time process data (temperature, pressure, flow, level)
• Historical data trends
• Alarm simulation

Mock Optimization Server

The mock optimization server (mock-optimization-server.py) simulates:

• Multiple optimization strategies
• Market data simulation
• Setpoint calculations
• Cost and energy savings analysis
• Confidence scoring

🔧 Management Commands

Service Management

# Start service
sudo systemctl start calejo-control-adapter

# Stop service
sudo systemctl stop calejo-control-adapter

# Check status
sudo systemctl status calejo-control-adapter

# Enable auto-start
sudo systemctl enable calejo-control-adapter

Application Management

# Health check
/opt/calejo-control-adapter/scripts/health-check.sh

# Full backup
/opt/calejo-control-adapter/scripts/backup-full.sh

# Restore from backup
/opt/calejo-control-adapter/scripts/restore-full.sh <backup-file>

# View logs
sudo docker-compose logs -f app

📁 Directory Structure

/opt/calejo-control-adapter/     # Main application directory
├── src/                         # Source code
├── static/                      # Static files (dashboard)
├── config/                      # Configuration files
├── scripts/                     # Management scripts
├── monitoring/                  # Monitoring configuration
├── tests/                       # Test files
└── docker-compose.yml           # Docker Compose configuration

/var/log/calejo/                 # Application logs
/etc/calejo/                     # Configuration files
/var/backup/calejo/              # Backup files

🌐 Access Points

After deployment, access the system at:

• Dashboard: http://<server-ip>:8080/dashboard
• REST API: http://<server-ip>:8080
• Health Check: http://<server-ip>:8080/health
• Mock SCADA (OPC UA): opc.tcp://<server-ip>:4840
• Mock SCADA (Modbus): <server-ip>:502

🔒 Security Considerations

Default Credentials

The deployment includes security validation that warns about:

• Default database credentials
• Unsecured communication
• Open ports

Recommended Security Practices

1. Change default passwords in configuration
2. Enable authentication in production
3. Use SSL/TLS for external communication
4. Configure firewall to restrict access
5. Regular security updates

📈 Monitoring and Maintenance

Health Monitoring

# Regular health checks
/opt/calejo-control-adapter/scripts/health-check.sh

# Monitor logs
sudo tail -f /var/log/calejo/*.log

Backup Strategy

# Schedule regular backups (add to crontab)
0 2 * * * /opt/calejo-control-adapter/scripts/backup-full.sh

# Manual backup
/opt/calejo-control-adapter/scripts/backup-full.sh

Performance Monitoring

The deployment includes:

• Prometheus metrics collection
• Grafana dashboards
• Health monitoring endpoints
• Log aggregation

🐛 Troubleshooting

Common Issues

1. Application not starting

   # Check Docker status
   sudo systemctl status docker
   
   # Check application logs
   sudo docker-compose logs app
   

2. Dashboard not accessible

   # Check if application is running
   curl http://localhost:8080/health
   
   # Check firewall settings
   sudo ufw status
   

3. Mock servers not working

   # Check if required ports are available
   sudo netstat -tulpn | grep -E ':(4840|502|8081)'
   

Log Files

• Application logs: /var/log/calejo/
• Docker logs: sudo docker-compose logs
• System logs: /var/log/syslog

📞 Support

For deployment issues:

1. Check this deployment guide
2. Run validation script: ./validate-deployment.sh
3. Check logs in /var/log/calejo/
4. Review test results from test-e2e-deployment.py

🎯 Next Steps After Deployment

1. Validate deployment with ./validate-deployment.sh
2. Run end-to-end tests with python test-e2e-deployment.py
3. Configure monitoring in Grafana
4. Set up backups with cron jobs
5. Test integration with real SCADA/optimization systems
6. Train users on dashboard usage

---

Deployment Status: ✅ Ready for Production Last Updated: $(date) Version: 1.0.0