env_backend.template

# ============================================================================
# ENEO BACKEND ENVIRONMENT CONFIGURATION - PRODUCTION DEPLOYMENT
# ============================================================================
# This template is for production Docker deployments using docker-compose.yml
# Copy values from your development .env or configure for your environment
# ============================================================================

# ----------------------------------------------------------------------------
# Infrastructure (REQUIRED)
# ----------------------------------------------------------------------------
# PostgreSQL database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme    # CHANGE THIS FOR PRODUCTION!
POSTGRES_PORT=5432
POSTGRES_HOST=db              # Docker service name
POSTGRES_DB=eneo

# Redis cache
REDIS_HOST=redis              # Docker service name
REDIS_PORT=6379

# ----------------------------------------------------------------------------
# Security (REQUIRED)
# ----------------------------------------------------------------------------
API_PREFIX=/api/v1
API_KEY_LENGTH=64
API_KEY_HEADER_NAME=X-API-Key
JWT_AUDIENCE=*
JWT_ISSUER=ENEO
JWT_EXPIRY_TIME=86400                       # seconds (24 hours)
JWT_ALGORITHM=HS256

# JWT_SECRET - CRITICAL FOR PRODUCTION
# Signs OIDC state tokens and user authentication tokens
# WARNING: MUST be changed from default for production!
# Minimum strength: 32 characters (256+ bits)
# Generate strong secret: python -c 'import secrets; print(secrets.token_hex(32))'
JWT_SECRET=

JWT_TOKEN_PREFIX=Bearer
URL_SIGNING_KEY=

# ----------------------------------------------------------------------------
# Authentication Configuration
# ----------------------------------------------------------------------------
# Glossary:
#   IdP = Identity Provider (Auth0, Azure AD, Keycloak, etc.)
#   OIDC = OpenID Connect (authentication protocol built on OAuth 2.0)
#   JWKS = JSON Web Key Set (public keys used to verify JWT signatures)
#
# Choose ONE of two modes:
#   1. Single-Tenant OIDC: One shared IdP for all users (recommended for most)
#   2. Multi-Tenant Federation: Each tenant has their own IdP (enterprise)
# ----------------------------------------------------------------------------

# PUBLIC_ORIGIN (REQUIRED for OIDC authentication)
# The externally-reachable URL where users access Eneo
# Used to construct OIDC redirect_uri (e.g., {PUBLIC_ORIGIN}/auth/callback)
# Must match:
#   1. What users see in their browser address bar
#   2. What's registered in your OIDC provider (Auth0, Azure AD, etc.)
#   3. Frontend PUBLIC_ORIGIN setting
# Examples:
#   Production: PUBLIC_ORIGIN=https://eneo.yourdomain.com
PUBLIC_ORIGIN=

# SINGLE-TENANT OIDC MODE (Default - Recommended)
# Direct login via one identity provider for all users
# ----------------------------------------------------------------------------
# OIDC discovery endpoint URL (auto-configures authorization/token/jwks endpoints)
# Examples:
#   Auth0: https://{your-domain}.auth0.com/.well-known/openid-configuration
#   Azure/Entra ID: https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
#   Keycloak: https://{keycloak-url}/realms/{realm-name}/.well-known/openid-configuration
OIDC_DISCOVERY_ENDPOINT=

# OIDC client credentials (from your IdP application registration)
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=

# [OPTIONAL] OIDC tenant ID (for backward compatibility with user creation)
OIDC_TENANT_ID=

# FEDERATION MODE
# ----------------------------------------------------------------------------
# Controls how OIDC/IdP configuration is managed:
#
# FALSE (default) - Single-Tenant via Environment Variables:
#   - Uses OIDC_* variables above (OIDC_DISCOVERY_ENDPOINT, OIDC_CLIENT_ID, etc.)
#   - Requires backend restart to change OIDC settings
#   - Simplest setup for single-organization deployments
#
# TRUE - Federation via Sysadmin API:
#   - Configure IdP settings via PUT /api/v1/sysadmin/tenants/{tenant_id}/federation
#   - Changes take effect immediately (no restart required)
#   - Requires ENCRYPTION_KEY (secrets are encrypted at rest)
#   - Use cases:
#     a) Multi-tenant: Each tenant has their own IdP (Entra ID, Okta, Auth0, etc.)
#     b) Single-tenant with API management: One tenant, but manage OIDC via API
#        instead of environment variables (useful for dynamic configuration)
# ----------------------------------------------------------------------------
FEDERATION_PER_TENANT_ENABLED=false

# OIDC Safety Controls
# ----------------------------------------------------------------------------
# [OPTIONAL] OIDC state JWT lifetime (default: 600 = 10 minutes)
OIDC_STATE_TTL_SECONDS=600

# [OPTIONAL] Grace period for redirect URI changes (default: 600 = 10 minutes)
OIDC_REDIRECT_GRACE_PERIOD_SECONDS=600

# [OPTIONAL] Strict redirect URI validation (default: true)
STRICT_OIDC_REDIRECT_VALIDATION=true

# [OPTIONAL] Clock drift tolerance for OIDC JWT validation (default: 120 seconds)
# Prevents "token not yet valid" errors when IdP server clock is slightly ahead
OIDC_CLOCK_LEEWAY_SECONDS=120

# ----------------------------------------------------------------------------
# Encryption & Multi-Tenant Features
# ----------------------------------------------------------------------------
# ENCRYPTION_KEY is REQUIRED when enabling:
#   - TENANT_CREDENTIALS_ENABLED=true (tenant-specific LLM API keys)
#   - FEDERATION_PER_TENANT_ENABLED=true (tenant-specific IdPs)
#
# Generate key:
#   Development: uv run python -m intric.cli.generate_encryption_key
#   Production:  docker compose run --rm backend python -m intric.cli.generate_encryption_key
#   Alternative: python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
#
# Format: 44-character base64-encoded Fernet key
# Example: FNVdDyfq0lBPAvjz_WS-9PB2UQzkbqCnwuA4KU9UbPU=
# WARNING: Backup this key securely - cannot decrypt without it
# ----------------------------------------------------------------------------
ENCRYPTION_KEY=

# Tenant-specific LLM credentials
# Enable municipalities to configure their own API keys per tenant
TENANT_CREDENTIALS_ENABLED=false

# ----------------------------------------------------------------------------
# LLM Provider API Keys (REQUIRED - At least ONE provider)
# ----------------------------------------------------------------------------
# How API keys are resolved depends on TENANT_CREDENTIALS_ENABLED:
#
# SINGLE-TENANT / GLOBAL FALLBACK MODE (TENANT_CREDENTIALS_ENABLED=false):
#   Use this when running Eneo for one organization (not multi-tenant SaaS).
#   - You CAN set keys here in .env (convenient for single deployments)
#   - You CAN ALSO configure keys via the credentials API endpoint
#   - If tenant has no key configured → falls back to these global keys
#   - If tenant HAS a key configured → tenant key is used (API takes priority)
#
# STRICT MULTI-TENANT MODE (TENANT_CREDENTIALS_ENABLED=true):
#   Use this for multi-tenant SaaS where each tenant pays their own LLM bills.
#   - Each tenant MUST configure their own keys via credentials API
#   - NO fallback to global keys (prevents billing confusion between tenants)
#   - These .env keys are ignored; only tenant-configured keys work
# ----------------------------------------------------------------------------

# OpenAI (GPT models)
# Get from: https://platform.openai.com/api-keys
OPENAI_API_KEY=

# Anthropic (Claude models)
# Get from: https://console.anthropic.com/
ANTHROPIC_API_KEY=

# Google Gemini
GEMINI_API_KEY=

# Azure OpenAI (Requires ALL 5 fields below to work)
AZURE_API_KEY=
AZURE_ENDPOINT=
AZURE_API_BASE=
AZURE_MODEL_DEPLOYMENT=
AZURE_API_VERSION=2024-02-15-preview

# Other LLM Providers
MISTRAL_API_KEY=
OVHCLOUD_API_KEY=

# Flux (Image generation)
FLUX_API_KEY=

# Tavily (Web search)
TAVILY_API_KEY=

# Self-hosted services
INFINITY_URL=

# vLLM (Self-hosted models)
VLLM_MODEL_URL=
VLLM_API_KEY=

# Super API keys (system administration)
ENEO_SUPER_API_KEY=
ENEO_SUPER_DUPER_API_KEY=
# NOTE: INTRIC_SUPER_API_KEY / INTRIC_SUPER_DUPER_API_KEY are still accepted but deprecated (removed in v3.0)

# ----------------------------------------------------------------------------
# Database Connection Pool Configuration
# ----------------------------------------------------------------------------
# Controls PostgreSQL connection pooling. Each container has its own pool.
#
# ⚠️  API STARVATION PREVENTION
# Reserve ≥40% of DB connections for API: WORKER_MAX_JOBS ≤ 0.6 × pool_max
# If workers consume all connections, API requests timeout during crawling.
#
# RECOMMENDED TUNING:
#   Small (8GB):   POOL_SIZE=10, OVERFLOW=5  → WORKER_MAX_JOBS=8
#   Medium (16GB): POOL_SIZE=20, OVERFLOW=10 → WORKER_MAX_JOBS=15
#   Large (32GB+): POOL_SIZE=30, OVERFLOW=20 → WORKER_MAX_JOBS=25
#
# Symptoms of misconfiguration: API timeouts, "QueuePool limit reached" errors
# ----------------------------------------------------------------------------
# Base pool size - permanent connections
DB_POOL_SIZE=20
# Extra connections above pool_size (pool_max = size + overflow = 30)
DB_POOL_MAX_OVERFLOW=10
# Seconds to wait for connection before error (increase for high-traffic)
DB_POOL_TIMEOUT=30
# Verify connections before use - prevents stale connection errors (KEEP TRUE)
DB_POOL_PRE_PING=true
# Recycle connections after N seconds (-1 = never, set to 3600 for cloud DBs)
# DB_POOL_RECYCLE=-1
# Log connections held >60s - use for debugging pool exhaustion only
# DB_POOL_DEBUG=false

# ----------------------------------------------------------------------------
# Background Worker Configuration
# ----------------------------------------------------------------------------
# Controls ARQ (Async Redis Queue) worker pool and per-tenant concurrency fairness.
# ARQ processes background jobs like web crawling, document processing, etc.
#
# NOTE: RUN_AS_WORKER is set in docker-compose.yml to run the container as
# a background task processor instead of HTTP server. Both backend and worker
# containers use the same image; run.sh detects RUN_AS_WORKER=true to launch
# the ARQ worker instead of Gunicorn.
#
# VOLUMES: Ensure both backend and worker services have these volumes in docker-compose.yml:
#   - eneo_backend_data:/app/data
#   - eneo_temp_files:/tmp  # Also used for audit log exports (/tmp/exports)
# ----------------------------------------------------------------------------
# ⚠️  WORKER_MAX_JOBS ≤ 0.6 × (DB_POOL_SIZE + DB_POOL_MAX_OVERFLOW)
# Crawl jobs hold DB connections for hours. See "Database Connection Pool" above.
# ----------------------------------------------------------------------------
# Max concurrent jobs across all tenants
# Memory: 100-500MB per job. With default pool (30), safe max is 18.
WORKER_MAX_JOBS=15

# Max concurrent jobs per tenant (prevents "noisy neighbor" problem)
# In multi-tenant deployments, prevents one tenant from monopolizing all worker slots
# Set to 0 to disable (not recommended for multi-tenant production)
TENANT_WORKER_CONCURRENCY_LIMIT=4

# Semaphore TTL - auto-cleanup for crashed workers
# CRITICAL: Must be > CRAWL_MAX_LENGTH to prevent premature lock release
# If TTL < crawl duration, slot expires mid-crawl causing tenant lockout
# Formula: TENANT_WORKER_SEMAPHORE_TTL_SECONDS > CRAWL_MAX_LENGTH + 1 hour buffer
# Default: 39600s (11 hours) > 36000s (10 hours) + 1 hour buffer
TENANT_WORKER_SEMAPHORE_TTL_SECONDS=39600  # 11 hours

# ============================================================================
# WEB CRAWLER SETTINGS
# ============================================================================

# --- BASIC SETTINGS ---------------------------------------------------------

# How long a single crawl can run (seconds). Default: 10 hours
# Large municipal websites may need 6-10 hours for full crawl
CRAWL_MAX_LENGTH=36000

# Maximum pages to crawl per website
CLOSESPIDER_ITEMCOUNT=20000

# Maximum file size the crawler will download (bytes). Default: 10MB
DOWNLOAD_MAX_SIZE=10485760

# Follow robots.txt rules (recommended)
OBEY_ROBOTS=true

# Automatically slow down to not overload target websites
AUTOTHROTTLE_ENABLED=true

# --- ADVANCED SETTINGS ------------------------------------------------------

# Pages saved per database write. Lower = less data loss on crash, higher = faster
CRAWL_PAGE_BATCH_SIZE=100

# Retry configuration for failed pages during crawl
# CRAWL_PAGE_MAX_RETRIES=3           # Maximum retries per page (default: 3)
# CRAWL_PAGE_RETRY_DELAY=1.0         # Initial retry delay in seconds (exponential backoff)

# Parallel embedding API calls per crawl
CRAWL_EMBEDDING_CONCURRENCY=3

# How often crawler reports it's still running (seconds)
CRAWL_HEARTBEAT_INTERVAL_SECONDS=300

# Stop crawler after this many missed heartbeats
CRAWL_HEARTBEAT_MAX_FAILURES=3

# Cancel old jobs for same website when user starts a new crawl (minutes)
CRAWL_STALE_THRESHOLD_MINUTES=30

# Mark stuck/crashed jobs as failed after this time (hours)
# Must be > CRAWL_MAX_LENGTH to avoid killing valid long crawls
ORPHAN_CRAWL_RUN_TIMEOUT_HOURS=12

# Reject jobs waiting in queue longer than this (seconds). Prevents backlog
CRAWL_JOB_MAX_AGE_SECONDS=1800

# --- OPTIONAL: Queue Throttling ---------------------------------------------
# Spreads out scheduled crawls to prevent worker overload
# Rate: releases BATCH_SIZE jobs every INTERVAL seconds

CRAWL_FEEDER_ENABLED=true
CRAWL_FEEDER_INTERVAL_SECONDS=10
CRAWL_FEEDER_BATCH_SIZE=10

# ----------------------------------------------------------------------------
# Web Crawling Configuration
# ----------------------------------------------------------------------------
# [OPTIONAL] Max crawl duration (default: 14400 = 4 hours)
CRAWL_MAX_LENGTH=14400
# [OPTIONAL] Max items before stopping (default: 20000)
CLOSESPIDER_ITEMCOUNT=20000
# [OPTIONAL] Max file download size in bytes (default: 10485760 = 10MB)
# Separate from UPLOAD_MAX_FILE_SIZE - controls crawler's DOWNLOAD_MAXSIZE
DOWNLOAD_MAX_SIZE=10485760
# [OPTIONAL] Respect robots.txt (default: True)
OBEY_ROBOTS=True
# [OPTIONAL] Auto-throttle requests (default: True)
AUTOTHROTTLE_ENABLED=True

# ----------------------------------------------------------------------------
# Audit Log Export Configuration
# ----------------------------------------------------------------------------
# [OPTIONAL] Directory for storing audit log export files
# Default: /tmp/exports (uses existing /tmp volume, no extra config needed)
# The /tmp directory is world-writable and already mounted via eneo_temp_files volume
# Override only if you need a custom location with appropriate permissions
# Check logs for "[EXPORT CONFIG]" messages if exports aren't working
# EXPORT_DIR=/tmp/exports

# [OPTIONAL] Max concurrent exports per tenant (default: 2)
# Prevents one tenant from overloading the system with many exports
EXPORT_MAX_CONCURRENT_PER_TENANT=2

# [OPTIONAL] Export file retention period in hours (default: 24)
# Files older than this are automatically cleaned up by daily cron job (03:00 UTC)
EXPORT_MAX_AGE_HOURS=24

# ============================================================================
# FEATURE FLAGS
# ============================================================================
USING_ACCESS_MANAGEMENT=true
USING_AZURE_MODELS=false
USING_IAM=false
USING_IMAGE_GENERATION=false
USING_CRAWL=true
TESTING=false
DEV=false

# ============================================================================
# FILE UPLOAD LIMITS
# ============================================================================
UPLOAD_FILE_TO_SESSION_MAX_SIZE=10485760    # 10MB - max file size in chat session
UPLOAD_IMAGE_TO_SESSION_MAX_SIZE=10485760   # 10MB - max image size in chat session
UPLOAD_MAX_FILE_SIZE=10485760               # 10MB - global upload limit
TRANSCRIPTION_MAX_FILE_SIZE=10485760        # 10MB - max audio file for transcription
MAX_IN_QUESTION=1                           # Max file attachments per chat message

# ----------------------------------------------------------------------------
# Integration OAuth Callbacks
# ----------------------------------------------------------------------------
OAUTH_CALLBACK_URL=
CONFLUENCE_CLIENT_ID=
CONFLUENCE_CLIENT_SECRET=
SHAREPOINT_CLIENT_ID=
SHAREPOINT_CLIENT_SECRET=

# ----------------------------------------------------------------------------
# Default Tenant & User (First-time Bootstrap)
# ----------------------------------------------------------------------------
# These credentials are used by init_db.py to create the initial tenant and user.
# The default credentials below match the DEPLOYMENT.md guide.
#
# IMPORTANT: Change the password after first login!
#
# If tenant/user already exist, init_db.py will skip creation (safe to re-run).
# ----------------------------------------------------------------------------
DEFAULT_TENANT_NAME=ExampleTenant
DEFAULT_TENANT_QUOTA_LIMIT=10737418240
DEFAULT_USER_NAME=ExampleUser
DEFAULT_USER_EMAIL=user@example.com
DEFAULT_USER_PASSWORD=Password1!

# ----------------------------------------------------------------------------
# Migration & Maintenance
# ----------------------------------------------------------------------------
# Auto-recalculate usage stats threshold for model migrations
MIGRATION_AUTO_RECALC_THRESHOLD=30

# ----------------------------------------------------------------------------
# Logging
# ----------------------------------------------------------------------------
# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
# Recommended for production: INFO
LOGLEVEL=INFO

# ----------------------------------------------------------------------------
# DEPRECATED: MobilityGuard and Zitadel variables are no longer used.
# Use OIDC_DISCOVERY_ENDPOINT, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET above.
# ----------------------------------------------------------------------------