Environment Variables Reference¶

Complete reference for all environment variables used by Champa Intelligence.

Overview¶

Champa Intelligence uses environment variables for configuration to support different deployment environments (development, staging, production) and to keep secrets out of version control.

Configuration Priority:

Environment variables (highest priority)
.env file
config.py defaults (lowest priority)

Required Variables¶

These variables must be set for Champa Intelligence to function:

Database Configuration¶

Variable	Description	Example	Default
`DB_NAME`	Camunda database name	`camunda`	`camunda`
`DB_USER`	Database username	`camunda`	`camunda`
`DB_PASSWORD`	Database password	`secure_pass_123`	Required
`DB_HOST`	Database hostname	`localhost`	`localhost`
`DB_PORT`	Database port	`5432`	`5432`

System Database¶

Variable	Description	Example	Default
`SYSTEM_DB_ENABLED`	Enable dedicated system DB	`true`	`true`
`SYSTEM_DB_NAME`	System database name	`champa_system`	`champa_system`
`SYSTEM_DB_USER`	System DB username	`champa_user`	`champa_user`
`SYSTEM_DB_PASSWORD`	System DB password	`strong_pass_456`	Required
`SYSTEM_DB_HOST`	System DB hostname	`localhost`	`localhost`
`SYSTEM_DB_PORT`	System DB port	`5433`	`5433`
`AUTH_DB_SCHEMA`	Auth schema name	`auth`	`auth`

Security¶

Variable	Description	Example	Default
`JWT_SECRET`	JWT signing secret (32+ chars)	`32_char_random_string`	Required
`JWT_EXPIRATION_HOURS`	JWT token expiration	`24`	`24`
`APP_SECRET_KEY`	Flask secret key (32+ chars)	`32_char_random_string`	Required

Optional Variables¶

Redis Configuration¶

Variable	Description	Example	Default
`REDIS_ENABLED`	Enable Redis caching	`true`	`true`
`REDIS_HOST`	Redis hostname	`localhost`	`localhost`
`REDIS_PORT`	Redis port	`6379`	`6379`
`REDIS_PASSWORD`	Redis password	`redis_pass`	`""`
`REDIS_DB`	Redis database number	`0`	`0`
`REDIS_SSL`	Enable SSL for Redis	`false`	`false`
`REDIS_CLUSTER`	Enable cluster mode	`false`	`false`
`REDIS_SESSION_TTL`	Session cache TTL (seconds)	`3600`	`3600`
`REDIS_SESSION_PREFIX`	Session key prefix	`session:`	`session:`
`REDIS_CACHE_TTL`	Query cache TTL (seconds)	`3600`	`3600`
`REDIS_CACHE_PREFIX`	Cache key prefix	`cache:`	`cache:`

Redis Sentinel (High Availability):

Variable	Description	Example	Default
`REDIS_SENTINEL_ENABLED`	Enable Sentinel	`false`	`false`
`REDIS_SENTINEL_SERVICE`	Sentinel service name	`redis-sentinel`	`redis-sentinel`
`REDIS_SENTINEL_PORT`	Sentinel port	`26379`	`26379`
`REDIS_MASTER_NAME`	Master name	`mymaster`	`mymaster`

AI Configuration¶

Variable	Description	Example	Default
`GOOGLE_API_KEY`	Google Gemini API key	`AIzaSyD...`	Required for AI

Camunda API Access¶

Variable	Description	Example	Default
`CAMUNDA_API_USER`	Camunda REST API username	`demo`	`demo`
`CAMUNDA_API_PASSWORD`	Camunda REST API password	`demo`	`demo`

Application Settings¶

Variable	Description	Example	Default
`FLASK_ENV`	Flask environment	`production`	`production`
`DEBUG`	Enable debug mode	`false`	`false`
`LOG_LEVEL`	Logging level	`INFO`	`INFO`
`TZ`	Timezone	`Europe/Kiev`	System default

Gunicorn Configuration¶

Variable	Description	Example	Default
`GUNICORN_WORKERS`	Number of worker processes	`4`	`(2×CPU)+1`
`GUNICORN_THREADS`	Threads per worker	`2`	`2`
`GUNICORN_TIMEOUT`	Request timeout (seconds)	`300`	`300`

Variable Types and Validation¶

Type Casting¶

Environment variables are automatically cast to appropriate types:

# Boolean
REDIS_ENABLED = get_env('REDIS_ENABLED', True, cast_type=bool)
# Accepts: true, True, 1, yes, on → True
# Accepts: false, False, 0, no, off → False

# Integer
DB_PORT = get_env('DB_PORT', 5432, cast_type=int)

# Float
THRESHOLD = get_env('THRESHOLD', 0.95, cast_type=float)

# String (default)
DB_NAME = get_env('DB_NAME', 'camunda')

Validation Rules¶

On startup, Champa Intelligence validates:

Required variables are set

DB_PASSWORD, JWT_SECRET, APP_SECRET_KEY

Secret lengths

JWT_SECRET >= 32 characters
APP_SECRET_KEY >= 32 characters

Database connectivity

DB_HOST is reachable
Credentials are valid
Required tables exist

Redis connectivity (if enabled)

REDIS_HOST is reachable
Authentication succeeds

Validation errors are logged and cause startup failure.

Environment-Specific Configuration¶

Development¶

# .env.development
FLASK_ENV=development
DEBUG=true
LOG_LEVEL=DEBUG

# Use local services
DB_HOST=localhost
DB_PORT=5555
REDIS_HOST=localhost
REDIS_PORT=6379

# Relaxed security for testing
JWT_EXPIRATION_HOURS=168  # 7 days

Staging¶

# .env.staging
FLASK_ENV=production
DEBUG=false
LOG_LEVEL=INFO

# Staging database
DB_HOST=staging-db.internal
DB_PASSWORD=${STAGING_DB_PASSWORD}

# Enable Redis
REDIS_ENABLED=true
REDIS_HOST=staging-redis.internal

# Standard security
JWT_EXPIRATION_HOURS=24

Production¶

# .env.production
FLASK_ENV=production
DEBUG=false
LOG_LEVEL=WARNING

# Production database (read-only)
DB_HOST=prod-db.internal
DB_PASSWORD=${PROD_DB_PASSWORD}

# Redis cluster
REDIS_ENABLED=true
REDIS_CLUSTER=true
REDIS_HOST=prod-redis-cluster.internal

# Strict security
JWT_EXPIRATION_HOURS=8
GUNICORN_WORKERS=16

Secret Management¶

Generating Secure Secrets¶

# JWT Secret (32 characters)
openssl rand -hex 32

# App Secret Key (32 characters)
openssl rand -hex 32

# Database Password (32 characters)
openssl rand -base64 32

# Redis Password (24 characters)
openssl rand -base64 24

Using Docker Secrets¶

docker-compose.yml:

services:
  champa-intelligence:
    secrets:
      - db_password
      - jwt_secret
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
      JWT_SECRET_FILE: /run/secrets/jwt_secret

secrets:
  db_password:
    file: ./secrets/db_password.txt
  jwt_secret:
    file: ./secrets/jwt_secret.txt

Modify security/env_config.py to read from files:

def get_env_or_file(key: str, default: Any = None):
    """Read from env var or _FILE variant"""
    file_key = f"{key}_FILE"
    if os.getenv(file_key):
        with open(os.getenv(file_key), 'r') as f:
            return f.read().strip()
    return os.getenv(key, default)

Using Kubernetes Secrets¶

secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: champa-secrets
type: Opaque
stringData:
  db-password: "your_db_password"
  jwt-secret: "your_jwt_secret"
  app-secret-key: "your_app_secret"

deployment.yaml:

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: champa-secrets
        key: db-password
  - name: JWT_SECRET
    valueFrom:
      secretKeyRef:
        name: champa-secrets
        key: jwt-secret

Configuration Loading Priority¶

Environment variables (highest)
Docker secrets (if configured)
.env file
config.py defaults (lowest)

Example:

# Priority demonstration
DB_HOST = os.getenv('DB_HOST')  # 1. Check environment
if not DB_HOST:
    DB_HOST = read_from_env_file('.env', 'DB_HOST')  # 2. Check .env
if not DB_HOST:
    DB_HOST = 'localhost'  # 3. Use default

Debugging Configuration¶

View Current Configuration¶

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

# View non-sensitive config summary
curl http://localhost:8088/health/api/config

Validate Configuration¶

# In Python shell
from security.env_config import get_config_summary, validate_config

# Get configuration summary
config = get_config_summary()
print(json.dumps(config, indent=2))

# Validate configuration
try:
    validate_config()
    print("✓ Configuration is valid")
except ValueError as e:
    print(f"✗ Configuration errors: {e}")

Common Issues¶

Issue: Configuration not loading

# Solution: Check .env file exists and is readable
ls -la .env
cat .env | grep DB_PASSWORD

Issue: Secrets not working

# Solution: Verify secret generation
echo $JWT_SECRET | wc -c  # Should be 32+

Issue: Database connection fails

# Solution: Test connection manually
docker exec champa-intelligence python -c "
from db import execute_query
result = execute_query('SELECT 1')
print('Database connected:', result)
"

Security Best Practices¶

DO¶

✅ Use environment variables for secrets
✅ Generate strong random secrets (32+ chars)
✅ Rotate secrets every 90 days
✅ Use different secrets per environment
✅ Restrict file permissions (.env should be 600)
✅ Use Docker secrets in production
✅ Enable SSL for Redis in production
✅ Use read-only database credentials

DON'T¶

❌ Commit .env files to version control
❌ Use default passwords in production
❌ Share secrets between environments
❌ Store secrets in plain text files
❌ Use the same JWT_SECRET across deployments
❌ Enable DEBUG mode in production
❌ Use weak passwords (<24 characters)

Environment Variable Checklist¶

Pre-Deployment¶

[ ] All required variables set
[ ] Secrets generated (32+ characters)
[ ] Database credentials tested
[ ] Redis connection tested (if enabled)
[ ] Camunda API credentials verified
[ ] .env file has correct permissions (600)
[ ] .env file in .gitignore

Production¶

[ ] FLASK_ENV=production
[ ] DEBUG=false
[ ] Strong JWT_SECRET (32+ chars)
[ ] Strong APP_SECRET_KEY (32+ chars)
[ ] Redis enabled with password
[ ] Appropriate GUNICORN_WORKERS count
[ ] SSL enabled for Redis (if applicable)
[ ] Monitoring and logging configured

Next Steps¶

Configuration Guide - Detailed configuration
Installation Guide - Setup instructions
Security Model - Security details