CalejoControl/docs/INSTALLATION_CONFIGURATION.md

Calejo Control Adapter - Installation & Configuration Guide

Overview

This guide provides comprehensive instructions for installing and configuring the Calejo Control Adapter for municipal wastewater pump station optimization.

System Requirements

Hardware Requirements

Minimum Requirements

• CPU: 2 cores (x86-64)
• RAM: 4 GB
• Storage: 10 GB SSD
• Network: 1 Gbps Ethernet

Recommended Requirements

• CPU: 4 cores (x86-64)
• RAM: 8 GB
• Storage: 50 GB SSD
• Network: 1 Gbps Ethernet with redundancy

Production Requirements

• CPU: 8+ cores (x86-64)
• RAM: 16+ GB
• Storage: 100+ GB SSD with RAID
• Network: Dual 1 Gbps Ethernet

Software Requirements

Operating Systems

• Linux: Ubuntu 20.04+, CentOS 8+, RHEL 8+
• Container: Docker 20.10+, Podman 3.0+
• Virtualization: VMware ESXi 7.0+, Hyper-V 2019+

Dependencies

• Python: 3.9+
• PostgreSQL: 13+
• Redis: 6.0+ (optional, for caching)

Installation Methods

Method 1: Docker Container (Recommended)

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+

Quick Start

1. Clone the repository:

   git clone https://github.com/calejo/control-adapter.git
   cd control-adapter
   

2. Configure environment:

   cp config/.env.example .env
   # Edit .env with your configuration
   nano .env
   

3. Start the application:

   docker-compose up -d
   

4. Verify installation:

   docker-compose logs -f control-adapter
   

Docker Compose Configuration

version: '3.8'

services:
  control-adapter:
    image: calejo/control-adapter:latest
    container_name: calejo-control-adapter
    restart: unless-stopped
    ports:
      - "4840:4840"  # OPC UA
      - "502:502"    # Modbus TCP
      - "8080:8080"  # REST API
      - "8081:8081"  # Health Monitor
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - LOG_LEVEL=${LOG_LEVEL}
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      - ./certs:/app/certs
    networks:
      - calejo-network

  database:
    image: postgres:15
    container_name: calejo-database
    restart: unless-stopped
    environment:
      - POSTGRES_DB=calejo
      - POSTGRES_USER=control_reader
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - calejo-network

volumes:
  postgres_data:

networks:
  calejo-network:
    driver: bridge

Method 2: Manual Installation

Step 1: Install Dependencies

Ubuntu/Debian:

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python and dependencies
sudo apt install python3.9 python3.9-pip python3.9-venv postgresql postgresql-contrib

# Install system dependencies
sudo apt install build-essential libssl-dev libffi-dev

CentOS/RHEL:

# Install Python and dependencies
sudo yum install python39 python39-pip postgresql postgresql-server

# Install system dependencies
sudo yum install gcc openssl-devel libffi-devel

Step 2: Set Up PostgreSQL

# Initialize PostgreSQL
sudo postgresql-setup initdb
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql -c "CREATE DATABASE calejo;"
sudo -u postgres psql -c "CREATE USER control_reader WITH PASSWORD 'secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE calejo TO control_reader;"

Step 3: Install Application

# Clone repository
git clone https://github.com/calejo/control-adapter.git
cd control-adapter

# Create virtual environment
python3.9 -m venv venv
source venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Install application in development mode
pip install -e .

Step 4: Configure Application

# Copy configuration template
cp config/.env.example .env

# Edit configuration
nano .env

Step 5: Run Application

# Run in development mode
python -m src.main

# Or run with production settings
python -m src.main --config production.yml

Method 3: Kubernetes Deployment

Prerequisites

• Kubernetes cluster 1.24+
• Helm 3.8+
• Persistent volume provisioner

Helm Chart Installation

1. Add Helm repository:

   helm repo add calejo https://charts.calejo.com
   helm repo update
   

2. Create values file:

   # values-production.yaml
   image:
     repository: calejo/control-adapter
     tag: latest
     pullPolicy: Always
   
   database:
     enabled: true
     postgresql:
       auth:
         username: control_reader
         password: "${DB_PASSWORD}"
   
   service:
     type: LoadBalancer
     ports:
       - name: opcua
         port: 4840
         targetPort: 4840
       - name: modbus
         port: 502
         targetPort: 502
       - name: rest-api
         port: 8080
         targetPort: 8080
   
   ingress:
     enabled: true
     hosts:
       - host: control-adapter.calejo.com
         paths:
           - path: /
             pathType: Prefix
   

3. Install chart:

   helm install calejo-control-adapter calejo/control-adapter \
     --namespace calejo \
     --create-namespace \
     --values values-production.yaml
   

Configuration

Environment Variables

Database Configuration

# Database connection
DATABASE_URL=postgresql://control_reader:secure_password@localhost:5432/calejo
DB_MIN_CONNECTIONS=5
DB_MAX_CONNECTIONS=20
DB_QUERY_TIMEOUT=30

Protocol Configuration

# OPC UA Server
OPC_UA_ENDPOINT=opc.tcp://0.0.0.0:4840
OPC_UA_SECURITY_POLICY=Basic256Sha256

# Modbus TCP Server
MODBUS_HOST=0.0.0.0
MODBUS_PORT=502
MODBUS_MAX_CONNECTIONS=100

# REST API Server
REST_API_HOST=0.0.0.0
REST_API_PORT=8080
REST_API_CORS_ORIGINS=https://dashboard.calejo.com

Safety Configuration

# Safety framework
SAFETY_TIMEOUT_SECONDS=1200
EMERGENCY_STOP_TIMEOUT=300
MAX_SPEED_CHANGE_HZ_PER_MIN=30

# Default safety limits
DEFAULT_MIN_SPEED_HZ=20.0
DEFAULT_MAX_SPEED_HZ=50.0

Security Configuration

# Authentication
JWT_SECRET_KEY=your-secure-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_TOKEN_EXPIRE_MINUTES=60

# Audit logging
AUDIT_LOG_ENABLED=true
AUDIT_LOG_RETENTION_DAYS=365

Monitoring Configuration

# Health monitoring
HEALTH_MONITOR_PORT=8081
HEALTH_CHECK_INTERVAL=30

# Alert system
ALERT_EMAIL_ENABLED=true
ALERT_SMS_ENABLED=false
ALERT_WEBHOOK_ENABLED=true

Configuration Files

YAML Configuration

# config/production.yml
app:
  name: "Calejo Control Adapter"
  version: "2.0.0"
  environment: "production"

database:
  url: "${DATABASE_URL}"
  pool_size: 10
  max_overflow: 20
  pool_timeout: 30

protocols:
  opcua:
    endpoint: "opc.tcp://0.0.0.0:4840"
    security_policies:
      - "Basic256Sha256"
      - "Aes256Sha256RsaPss"
  
  modbus:
    host: "0.0.0.0"
    port: 502
    max_connections: 100
  
  rest_api:
    host: "0.0.0.0"
    port: 8080
    cors_origins:
      - "https://dashboard.calejo.com"

safety:
  timeout_seconds: 1200
  emergency_stop_timeout: 300
  default_limits:
    min_speed_hz: 20.0
    max_speed_hz: 50.0
    max_speed_change: 30.0

security:
  jwt_secret: "${JWT_SECRET_KEY}"
  token_expire_minutes: 60
  audit_log_enabled: true

Database Schema Configuration

-- Safety limits table
CREATE TABLE safety_limits (
    station_id VARCHAR(50) NOT NULL,
    pump_id VARCHAR(50) NOT NULL,
    hard_min_speed_hz DECIMAL(5,2) NOT NULL,
    hard_max_speed_hz DECIMAL(5,2) NOT NULL,
    hard_min_level_m DECIMAL(6,2),
    hard_max_level_m DECIMAL(6,2),
    hard_max_power_kw DECIMAL(8,2),
    max_speed_change_hz_per_min DECIMAL(5,2) NOT NULL,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (station_id, pump_id)
);

-- Emergency stop status table
CREATE TABLE emergency_stop_status (
    station_id VARCHAR(50) NOT NULL,
    pump_id VARCHAR(50),
    active BOOLEAN NOT NULL DEFAULT FALSE,
    activated_at TIMESTAMP,
    activated_by VARCHAR(100),
    reason TEXT,
    PRIMARY KEY (station_id, COALESCE(pump_id, 'STATION'))
);

-- Audit log table
CREATE TABLE compliance_audit_log (
    id SERIAL PRIMARY KEY,
    timestamp TIMESTAMP NOT NULL,
    event_type VARCHAR(50) NOT NULL,
    severity VARCHAR(20) NOT NULL,
    user_id VARCHAR(100),
    station_id VARCHAR(50),
    pump_id VARCHAR(50),
    ip_address INET,
    protocol VARCHAR(20),
    action VARCHAR(100),
    resource VARCHAR(200),
    result VARCHAR(50),
    reason TEXT,
    compliance_standard TEXT[],
    event_data JSONB,
    app_name VARCHAR(100),
    app_version VARCHAR(20),
    environment VARCHAR(20)
);

Security Configuration

Certificate Management

Generate SSL Certificates

# Generate private key
openssl genrsa -out server.key 2048

# Generate certificate signing request
openssl req -new -key server.key -out server.csr

# Generate self-signed certificate
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

# Combine for OPC UA
cat server.crt server.key > server.pem

OPC UA Certificate Configuration

opcua:
  certificate:
    server_cert: "/app/certs/server.pem"
    server_key: "/app/certs/server.key"
    ca_cert: "/app/certs/ca.crt"
  security:
    mode: "SignAndEncrypt"
    policy: "Basic256Sha256"

User Management

Default Users

# Default user configuration
default_users = [
    {
        "user_id": "admin_001",
        "username": "admin",
        "email": "admin@calejo.com",
        "role": "administrator",
        "password": "${ADMIN_PASSWORD}"
    },
    {
        "user_id": "operator_001",
        "username": "operator",
        "email": "operator@calejo.com",
        "role": "operator",
        "password": "${OPERATOR_PASSWORD}"
    }
]

Password Policy

security:
  password_policy:
    min_length: 12
    require_uppercase: true
    require_lowercase: true
    require_numbers: true
    require_special_chars: true
    max_age_days: 90

Network Configuration

Firewall Configuration

Required Ports

Port	Protocol	Purpose	Security
4840	TCP	OPC UA Server	Internal/Trusted
502	TCP	Modbus TCP	Internal/Trusted
8080	TCP	REST API	Internal/Trusted
8081	TCP	Health Monitor	Internal
5432	TCP	PostgreSQL	Internal

Example iptables Rules

# Allow OPC UA
iptables -A INPUT -p tcp --dport 4840 -s 192.168.1.0/24 -j ACCEPT

# Allow Modbus TCP
iptables -A INPUT -p tcp --dport 502 -s 10.0.0.0/8 -j ACCEPT

# Allow REST API
iptables -A INPUT -p tcp --dport 8080 -s 172.16.0.0/12 -j ACCEPT

# Default deny
iptables -A INPUT -j DROP

Network Segmentation

Recommended Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   SCADA Zone    │    │ Control Adapter │    │  Database Zone  │
│                 │    │                 │    │                 │
│ - Siemens WinCC │◄──►│ - OPC UA Server │◄──►│ - PostgreSQL    │
│ - EcoStruxure   │    │ - Modbus Server │    │ - Redis Cache   │
│ - FactoryTalk   │    │ - REST API      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
  192.168.1.0/24          172.16.1.0/24          10.0.1.0/24

Performance Tuning

Database Optimization

PostgreSQL Configuration

-- Performance tuning
ALTER SYSTEM SET shared_buffers = '2GB';
ALTER SYSTEM SET work_mem = '64MB';
ALTER SYSTEM SET maintenance_work_mem = '512MB';
ALTER SYSTEM SET effective_cache_size = '6GB';
ALTER SYSTEM SET random_page_cost = 1.1;

-- Restart PostgreSQL
SELECT pg_reload_conf();

Index Optimization

-- Create performance indexes
CREATE INDEX idx_audit_log_timestamp ON compliance_audit_log(timestamp);
CREATE INDEX idx_audit_log_event_type ON compliance_audit_log(event_type);
CREATE INDEX idx_safety_limits_station ON safety_limits(station_id, pump_id);

Application Tuning

Connection Pooling

database:
  pool_size: 20
  max_overflow: 40
  pool_recycle: 3600
  pool_timeout: 30

Protocol Performance

protocols:
  opcua:
    subscription_interval: 1000  # ms
    publishing_interval: 1000    # ms
    
  modbus:
    response_timeout: 5          # seconds
    byte_timeout: 1              # seconds
    
  rest_api:
    compression_enabled: true
    cache_timeout: 60            # seconds

Verification & Testing

Health Checks

Application Health

# Check REST API health
curl http://localhost:8080/api/v1/health

# Check OPC UA connectivity
opcua-client connect opc.tcp://localhost:4840

# Check Modbus connectivity
modbus-tcp read 127.0.0.1 502 40001 10

Database Connectivity

# Test database connection
psql "${DATABASE_URL}" -c "SELECT version();"

# Check database health
psql "${DATABASE_URL}" -c "SELECT count(*) FROM safety_limits;"

Smoke Tests

Run Basic Tests

# Run smoke tests
python -m pytest tests/deployment/smoke_tests.py -v

# Run all tests
python -m pytest tests/ -v

Verify Protocols

# Test OPC UA server
python tests/integration/test_opcua_integration.py

# Test Modbus server
python tests/integration/test_modbus_integration.py

# Test REST API
python tests/integration/test_rest_api_integration.py

Troubleshooting

Common Issues

Database Connection Issues

• Error: "Connection refused"
• Solution: Verify PostgreSQL is running and accessible
• Check: systemctl status postgresql

Protocol Server Issues

• Error: "Port already in use"
• Solution: Check for conflicting services
• Check: netstat -tulpn | grep :4840

Security Issues

• Error: "JWT token invalid"
• Solution: Verify JWT_SECRET_KEY is set correctly
• Check: Environment variable configuration

Log Analysis

Application Logs

# View application logs
docker-compose logs control-adapter

# View specific component logs
docker-compose logs control-adapter | grep "safety"

# Monitor real-time logs
docker-compose logs -f control-adapter

Database Logs

# View PostgreSQL logs
sudo tail -f /var/log/postgresql/postgresql-*.log

# Check database performance
psql "${DATABASE_URL}" -c "SELECT * FROM pg_stat_activity;"

---

This installation and configuration guide provides comprehensive instructions for deploying the Calejo Control Adapter in various environments. Always test configurations in a staging environment before deploying to production.