7.2 KiB

Raw Blame History

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

Clone and configure

git clone <repository-url>
cd calejo-control-adapter

# Copy and edit environment configuration
cp .env.example .env
# Edit .env with your settings

Start the application
```
docker-compose up -d
```

Verify deployment

# 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

Install dependencies

# 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

Set up PostgreSQL

sudo -u postgres psql
CREATE DATABASE calejo;
CREATE USER calejo WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE calejo TO calejo;
\q

Configure application

# 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"

Initialize database

# Run database initialization
psql -h localhost -U calejo -d calejo -f database/init.sql

Start the application
```
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:

-- 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

Firewall Configuration

# 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

SSL/TLS Configuration

# 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

Change Default Credentials
- Update JWT secret key
- Change API key
- Update database passwords
- Rotate user passwords
Access Control
- Implement network segmentation
- Use VPN for remote access
- Configure role-based access control

Backup and Recovery

Database Backups

# 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

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

Recovery Procedure

Database Recovery

# 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

Configuration Recovery

# 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

Database Connection Issues
- Check PostgreSQL service status
- Verify connection string
- Check firewall rules
Port Conflicts
- Use netstat -tulpn to check port usage
- Update configuration to use available ports
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

7.2 KiB Raw Blame History