CalejoControl/DEPLOYMENT.md

# Calejo Control Adapter - Deployment Guide

## Overview

The Calejo Control Adapter is a multi-protocol integration system for municipal wastewater pump stations with comprehensive safety and security features.

## Quick Start with Docker Compose

### Prerequisites
- Docker Engine 20.10+
- Docker Compose 2.0+
- At least 4GB RAM

### Deployment Steps

1. **Clone and configure**
   ```bash
   git clone <repository-url>
   cd calejo-control-adapter
   
   # Copy and edit environment configuration
   cp .env.example .env
   # Edit .env with your settings
   ```

2. **Start the application**
   ```bash
   docker-compose up -d
   ```

3. **Verify deployment**
   ```bash
   # Check container status
   docker-compose ps
   
   # Check application health
   curl http://localhost:8080/health
   
   # Access monitoring dashboards
   # Grafana: http://localhost:3000 (admin/admin)
   # Prometheus: http://localhost:9091
   ```

## Manual Installation

### System Requirements
- Python 3.11+
- PostgreSQL 14+
- 2+ CPU cores
- 4GB+ RAM
- 10GB+ disk space

### Installation Steps

1. **Install dependencies**
   ```bash
   # Ubuntu/Debian
   sudo apt update
   sudo apt install python3.11 python3.11-venv python3.11-dev postgresql postgresql-contrib
   
   # CentOS/RHEL
   sudo yum install python3.11 python3.11-devel postgresql postgresql-server
   ```

2. **Set up PostgreSQL**
   ```bash
   sudo -u postgres psql
   CREATE DATABASE calejo;
   CREATE USER calejo WITH PASSWORD 'secure_password';
   GRANT ALL PRIVILEGES ON DATABASE calejo TO calejo;
   \q
   ```

3. **Configure application**
   ```bash
   # Create virtual environment
   python3.11 -m venv venv
   source venv/bin/activate
   
   # Install Python dependencies
   pip install -r requirements.txt
   
   # Configure environment
   export DATABASE_URL="postgresql://calejo:secure_password@localhost:5432/calejo"
   export JWT_SECRET_KEY="your-secret-key-change-in-production"
   export API_KEY="your-api-key-here"
   ```

4. **Initialize database**
   ```bash
   # Run database initialization
   psql -h localhost -U calejo -d calejo -f database/init.sql
   ```

5. **Start the application**
   ```bash
   python -m src.main
   ```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://calejo:password@localhost:5432/calejo` |
| `JWT_SECRET_KEY` | JWT token signing key | `your-secret-key-change-in-production` |
| `API_KEY` | API access key | `your-api-key-here` |
| `OPCUA_HOST` | OPC UA server host | `localhost` |
| `OPCUA_PORT` | OPC UA server port | `4840` |
| `MODBUS_HOST` | Modbus server host | `localhost` |
| `MODBUS_PORT` | Modbus server port | `502` |
| `REST_API_HOST` | REST API host | `0.0.0.0` |
| `REST_API_PORT` | REST API port | `8080` |
| `HEALTH_MONITOR_PORT` | Prometheus metrics port | `9090` |

### Database Configuration

For production PostgreSQL configuration:

```sql
-- Optimize PostgreSQL for production
ALTER SYSTEM SET shared_buffers = '1GB';
ALTER SYSTEM SET effective_cache_size = '3GB';
ALTER SYSTEM SET work_mem = '16MB';
ALTER SYSTEM SET maintenance_work_mem = '256MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
ALTER SYSTEM SET wal_buffers = '16MB';
ALTER SYSTEM SET default_statistics_target = 100;

-- Restart PostgreSQL to apply changes
SELECT pg_reload_conf();
```

## Monitoring and Observability

### Health Endpoints

- **Basic Health**: `GET /health`
- **Detailed Health**: `GET /api/v1/health/detailed`
- **Metrics**: `GET /metrics` (Prometheus format)

### Key Metrics

- `calejo_app_uptime_seconds` - Application uptime
- `calejo_db_connections_active` - Active database connections
- `calejo_opcua_connections` - OPC UA client connections
- `calejo_modbus_connections` - Modbus connections
- `calejo_rest_api_requests_total` - REST API request count
- `calejo_safety_violations_total` - Safety violations detected

## Security Hardening

### Network Security

1. **Firewall Configuration**
   ```bash
   # Allow only necessary ports
   ufw allow 22/tcp    # SSH
   ufw allow 5432/tcp  # PostgreSQL
   ufw allow 8080/tcp  # REST API
   ufw allow 9090/tcp  # Prometheus
   ufw enable
   ```

2. **SSL/TLS Configuration**
   ```bash
   # Generate SSL certificates
   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
   
   # Configure in settings
   export TLS_ENABLED=true
   export TLS_CERT_PATH=/path/to/cert.pem
   export TLS_KEY_PATH=/path/to/key.pem
   ```

### Application Security

1. **Change Default Credentials**
   - Update JWT secret key
   - Change API key
   - Update database passwords
   - Rotate user passwords

2. **Access Control**
   - Implement network segmentation
   - Use VPN for remote access
   - Configure role-based access control

## Backup and Recovery

### Database Backups

```bash
# Daily backup script
#!/bin/bash
BACKUP_DIR="/backups/calejo"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup
pg_dump -h localhost -U calejo calejo > "$BACKUP_DIR/calejo_backup_$DATE.sql"

# Compress backup
gzip "$BACKUP_DIR/calejo_backup_$DATE.sql"

# Keep only last 7 days
find "$BACKUP_DIR" -name "calejo_backup_*.sql.gz" -mtime +7 -delete
```

### Application Data Backup

```bash
# Backup configuration and logs
tar -czf "/backups/calejo_config_$(date +%Y%m%d).tar.gz" config/ logs/
```

### Recovery Procedure

1. **Database Recovery**
   ```bash
   # Stop application
   docker-compose stop calejo-control-adapter
   
   # Restore database
   gunzip -c backup_file.sql.gz | psql -h localhost -U calejo calejo
   
   # Start application
   docker-compose start calejo-control-adapter
   ```

2. **Configuration Recovery**
   ```bash
   # Extract configuration backup
   tar -xzf config_backup.tar.gz -C /
   ```

## Performance Tuning

### Database Performance

- Monitor query performance with `EXPLAIN ANALYZE`
- Create appropriate indexes
- Regular VACUUM and ANALYZE operations
- Connection pooling configuration

### Application Performance

- Monitor memory usage
- Configure appropriate thread pools
- Optimize database connection settings
- Enable compression for large responses

## Troubleshooting

### Common Issues

1. **Database Connection Issues**
   - Check PostgreSQL service status
   - Verify connection string
   - Check firewall rules

2. **Port Conflicts**
   - Use `netstat -tulpn` to check port usage
   - Update configuration to use available ports

3. **Performance Issues**
   - Check system resources (CPU, memory, disk)
   - Monitor database performance
   - Review application logs

### Log Files

- Application logs: `logs/calejo.log`
- Database logs: PostgreSQL log directory
- System logs: `/var/log/syslog` or `/var/log/messages`

## Support and Maintenance

### Regular Maintenance Tasks

- Daily: Check application health and logs
- Weekly: Database backups and cleanup
- Monthly: Security updates and patches
- Quarterly: Performance review and optimization

### Monitoring Checklist

- [ ] Application responding to health checks
- [ ] Database connections stable
- [ ] No safety violations
- [ ] System resources adequate
- [ ] Backup procedures working

## Contact and Support

For technical support:
- Email: support@calejo-control.com
- Documentation: https://docs.calejo-control.com
- Issue Tracker: https://github.com/calejo/control-adapter/issues