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:

```bash
# 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**
   ```bash
   # 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**
   ```bash
   # 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:

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Backup Strategy

```bash
# 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**
   ```bash
   # Check Docker status
   sudo systemctl status docker
   
   # Check application logs
   sudo docker-compose logs app
   ```

2. **Dashboard not accessible**
   ```bash
   # Check if application is running
   curl http://localhost:8080/health
   
   # Check firewall settings
   sudo ufw status
   ```

3. **Mock servers not working**
   ```bash
   # 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