Configuration Guide¶

Complete guide to configuring Champa Intelligence for your Camunda 7 environment.

Configuration Files¶

Champa Intelligence uses multiple configuration files to manage different aspects of the application:

File	Purpose	Location
`config.py`	Main application configuration	Project root
`config_ai.py`	AI analysis settings	Project root
`security/env_config.py`	Environment variable parsing	`security/`
`.env`	Environment-specific secrets	Project root (gitignored)

Environment Variables¶

Creating .env File¶

# Copy template
cp .env.template .env

# Edit with your values
nano .env

Required Variables¶

Database Configuration¶

# Camunda Database (Customer DB - Read Access)
DB_NAME=camunda
DB_USER=camunda
DB_PASSWORD=your_secure_password
DB_HOST=your_camunda_host
DB_PORT=5432

# System Database (Champa's own DB)
SYSTEM_DB_ENABLED=true
SYSTEM_DB_NAME=champa_system
SYSTEM_DB_USER=champa_user
SYSTEM_DB_PASSWORD=strong_password_here
SYSTEM_DB_HOST=localhost
SYSTEM_DB_PORT=5433
AUTH_DB_SCHEMA=auth

Redis Configuration¶

REDIS_ENABLED=true
REDIS_HOST=localhost
REDIS_PORT=6377
REDIS_PASSWORD=redis_secure_password
REDIS_DB=0
REDIS_SSL=false
REDIS_CLUSTER=false
REDIS_SESSION_TTL=3600
REDIS_CACHE_TTL=3600

Security Secrets¶

# Generate secure secrets
JWT_SECRET=$(openssl rand -hex 32)
JWT_EXPIRATION_HOURS=24
APP_SECRET_KEY=$(openssl rand -hex 32)

AI Configuration¶

# Google Gemini API Key
GOOGLE_API_KEY=your_gemini_api_key_here

Camunda API Access¶

CAMUNDA_API_USER=demo
CAMUNDA_API_PASSWORD=demo

Gunicorn Configuration¶

GUNICORN_WORKERS=4
GUNICORN_THREADS=2
GUNICORN_TIMEOUT=300

Main Configuration (config.py)¶

Test Mode¶

# Enable/disable test mode
TEST = False  # Set to True for development

Camunda Nodes Configuration¶

CAMUNDA_NODES = {
    'production-node-1': 'http://camunda-node-1:8080/engine-rest',
    'production-node-2': 'http://camunda-node-2:8080/engine-rest',
    'production-node-3': 'http://camunda-node-3:8080/engine-rest'
}

Explanation: - Key: Node identifier (used in UI and metrics) - Value: Full REST API endpoint URL - Supports multiple nodes for cluster monitoring

JMX Exporter Configuration¶

JMX_EXPORTER_ENDPOINTS = {
    'production-node-1': 'http://camunda-node-1:9404/metrics',
    'production-node-2': 'http://camunda-node-2:9404/metrics',
    'production-node-3': 'http://camunda-node-3:9404/metrics'
}

# Metrics source: 'JMX Exporter' or 'micrometer'
JVM_METRICS_SOURCE = 'JMX Exporter'

JVM Metrics Sources: - 'JMX Exporter': For Camunda with JMX Prometheus exporter - 'micrometer': For Camunda with Micrometer (Quarkus/Spring Boot)

Business Key Configuration¶

# Delimiters used to parse business keys
BUSINESS_KEY_DELIMITERS = ['_', '-', ':']

Example: - Business key: ORDER_123456_CUSTOMER - Normalized to: ORDER (first segment before delimiter) - Used for journey monitoring across processes

Stuck Instance Detection¶

# Days of inactivity before flagging instance as stuck
STUCK_INSTANCE_DAYS = 7

Session Configuration¶

# Session timeout settings
SESSION_TTL_HOURS = 24
SESSION_TTL_REMEMBER_ME_DAYS = 30

External URLs¶

# Camunda Cockpit URL for deep linking
CAMUNDA_COCKPIT_URL = 'http://localhost:8080/camunda/app/cockpit/default/#'

# External CRM host for integration
EXTERNAL_CRM_HOST = 'https://your-crm-host.com'

Logging Configuration¶

Configure logging behavior in config.py:

LOG_CONFIG = {
    # Default log level
    'default_log_level': 'INFO',  # DEBUG, INFO, WARNING, ERROR, CRITICAL

    # Enable/disable specific log files
    'console': True,
    'app_log': True,
    'error_log': True,
    'access_log': True,
    'security_log': True,
    'database_log': True,
    'cache_log': True,
    'structured_log': True,
    'ai_log': True,

    # Skip logging for these endpoints (case-insensitive)
    'no_logging_endpoints': [
        '/static/',
        '/favicon.ico',
        '/health/ping',
        '.png',
        '.jpg',
        '.css'
    ],

    # Log rotation settings
    'max_bytes': 10 * 1024 * 1024,  # 10 MB
    'backup_count': 10,
    'error_backup_count': 20,
    'daily_backup_count': 30,
    'security_backup_count': 90,

    # Performance thresholds
    'slow_request_ms': 5000,  # Log warning for slow requests
    'slow_query_ms': 5000,    # Log warning for slow queries
}

Log Files Location: logs/ directory

Log File	Purpose	Retention
`champa_app.log`	General application logs	10 rotations
`champa_errors.log`	Error and exception logs	20 rotations
`champa_access.log`	HTTP request logs	30 days
`champa_security.log`	Authentication & authorization	90 days
`champa_database.log`	Database query logs	5 rotations
`champa_cache.log`	Redis cache operations	5 rotations
`champa_ai.log`	AI analysis operations	5 rotations
`champa_structured.jsonl`	Structured JSON logs	30 days

AI Configuration (config_ai.py)¶

Model Settings¶

# AI Model Selection
AI_MODEL_NAME = 'gemini-2.5-flash'

# Model Parameters
AI_TEMPERATURE = 0.8  # 0.0 (deterministic) to 1.0 (creative)
AI_TOP_P = 0.95
AI_TOP_K = 40
AI_RESPONSE_MODALITIES = ["TEXT"]

Temperature Guide: - 0.0-0.3: Factual, deterministic responses - 0.4-0.7: Balanced creativity and accuracy - 0.8-1.0: Creative, varied responses

Data Limits¶

# Maximum data sizes for AI processing
AI_MAX_PROMPT_CHARS = 180000
AI_MAX_XML_SECTION_CHARS = 700000
AI_DATA_SUMMARY_MAX_CHARS = 160000

Word Limits by Detail Level¶

AI_WORD_LIMITS = {
    'executive': 500,   # High-level summary
    'standard': 1000,   # Balanced detail
    'detailed': 2000    # Technical deep-dive
}

Performance Settings¶

# Parallel data fetching for faster analysis
AI_PARALLEL_DATA_FETCH_ENABLED = True
AI_PARALLEL_DB_MAX_WORKERS = 4

Caching¶

AI_CACHE_ENABLED = True
AI_CACHE_MAX_SIZE = 128
AI_CACHE_TTL_SECONDS = 3600  # 1 hour

Analysis Templates¶

AI_ENABLE_ANALYSIS_TEMPLATES = True

AI_ANALYSIS_TEMPLATES = [
    {
        'id': 'incident_investigation',
        'name': 'Incident Investigation',
        'description': 'Deep-dive into recent failures and incidents',
        'focus': 'incidents',
        'detail_level': 'detailed',
        'duration': '1_week',
        'include_bpmn_xml': True,
        'custom_guidelines': 'Focus on root causes and prevention'
    },
    # ... more templates
]

Database Configuration¶

Connection Pooling¶

Champa Intelligence uses psycopg2 connection pooling for efficient database access.

Default Pool Settings: - Minimum connections: 2 - Maximum connections: 20 - Connection timeout: 30 seconds

Configure via environment:

# In db/core.py (modify if needed)
DB_MIN_CONN = 2
DB_MAX_CONN = 20

Read-Only Access¶

Champa Intelligence requires read-only access to the Camunda database:

-- Grant read-only access to Camunda schema
GRANT CONNECT ON DATABASE camunda TO champa_user;
GRANT USAGE ON SCHEMA public TO champa_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO champa_user;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
GRANT SELECT ON TABLES TO champa_user;

System Database Setup¶

-- Create system database
CREATE DATABASE champa_system;

-- Create user
CREATE USER champa_user WITH PASSWORD 'strong_password';
GRANT ALL PRIVILEGES ON DATABASE champa_system TO champa_user;

-- Create auth schema
\c champa_system
CREATE SCHEMA IF NOT EXISTS auth;
GRANT ALL ON SCHEMA auth TO champa_user;

Redis Configuration¶

Connection Settings¶

REDIS_HOST=localhost
REDIS_PORT=6377
REDIS_PASSWORD=redis_secure_password
REDIS_DB=0

SSL Configuration¶

REDIS_SSL=false  # Set to true for SSL connections

Cluster Mode¶

REDIS_CLUSTER=false  # Set to true for Redis cluster

# Sentinel configuration (if using)
REDIS_SENTINEL_ENABLED=false
REDIS_SENTINEL_SERVICE=redis-sentinel
REDIS_SENTINEL_PORT=26379
REDIS_MASTER_NAME=mymaster

Cache TTL Settings¶

# Session cache TTL
REDIS_SESSION_TTL=3600  # 1 hour
REDIS_SESSION_PREFIX=session:

# Query cache TTL
REDIS_CACHE_TTL=3600  # 1 hour
REDIS_CACHE_PREFIX=cache:

Production Configuration¶

Performance Tuning¶

Gunicorn Workers¶

# Formula: (2 × CPU_CORES) + 1
GUNICORN_WORKERS=9  # For 4-core server
GUNICORN_THREADS=2
GUNICORN_TIMEOUT=300

Database Optimization¶

# Increase connection pool for high load
DB_MAX_CONN = 50

# Query timeout
DB_QUERY_TIMEOUT = 30  # seconds

Redis Optimization¶

# Increase memory limits
maxmemory 2gb
maxmemory-policy allkeys-lru

# Enable compression
REDIS_COMPRESSION=true

Security Hardening¶

Generate Strong Secrets¶

# JWT Secret (32+ characters)
JWT_SECRET=$(openssl rand -hex 32)

# App Secret Key (32+ characters)
APP_SECRET_KEY=$(openssl rand -hex 32)

# Database passwords (24+ characters)
openssl rand -base64 24

HTTPS Configuration¶

# Behind reverse proxy
FLASK_ENV=production
FORCE_HTTPS=true

Rate Limiting¶

Configure in reverse proxy (Nginx):

limit_req_zone $binary_remote_addr zone=champa_limit:10m rate=10r/s;

server {
    location / {
        limit_req zone=champa_limit burst=20;
    }
}

Development Configuration¶

Debug Mode¶

FLASK_ENV=development
DEBUG=true
LOG_LEVEL=DEBUG

Hot Reload¶

# Start with auto-reload
python app.py

Frontend Development¶

# Watch mode for frontend changes
npm run dev

Configuration Validation¶

Champa Intelligence validates configuration on startup:

def validate_config():
    """Validates critical configuration at startup"""
    errors = []

    # Check required variables
    if not DB_PASSWORD:
        errors.append("DB_PASSWORD is required")

    if not JWT_SECRET or len(JWT_SECRET) < 32:
        errors.append("JWT_SECRET must be at least 32 characters")

    if errors:
        raise ValueError("Configuration errors:\n" + "\n".join(f"  - {e}" for e in errors))

Check logs on startup:

docker logs champa-intelligence | grep "Configuration"

Configuration Best Practices¶

Security¶

Never commit secrets to version control
Use strong passwords (24+ characters)
Rotate secrets every 90 days
Use separate credentials for each environment
Enable audit logging for compliance

Performance¶

Enable Redis caching for production
Tune worker count based on CPU cores
Set appropriate timeouts for your workload
Monitor slow queries via logs
Use connection pooling for databases

Monitoring¶

Enable structured logging for analysis
Set up Prometheus scraping for metrics
Configure alerts for critical thresholds
Monitor disk usage for log rotation
Track cache hit rates in Redis

Troubleshooting Configuration¶

Database Connection Issues¶

# Test connection
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1;"

# Check permissions
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT current_user, session_user;"

Redis Connection Issues¶

# Test connection
redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD PING

# Check info
redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD INFO

Configuration Loading Issues¶

# Check environment variables
docker exec champa-intelligence env | grep DB_
docker exec champa-intelligence env | grep REDIS_

# View full config (without secrets)
curl http://localhost:8088/api/config/summary

Next Steps¶

Installation Guide - Set up Champa Intelligence
API Reference - API configuration
Troubleshooting - Common issues