299 lines
7.2 KiB
Markdown
299 lines
7.2 KiB
Markdown
# 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 |