Configuration¶

This document describes the settings architecture, environment variables, and configuration patterns for the Home Security Intelligence system.

Settings Architecture¶

The application uses Pydantic Settings for type-safe configuration management with environment variable support.

Source: backend/core/config.py:298-306

class Settings(BaseSettings):
    """Application settings loaded from environment variables."""

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
        extra="ignore",
    )

Settings Singleton Pattern¶

Settings are loaded once and cached using the @cache decorator.

Source: backend/core/config.py (end of file)

@cache
def get_settings() -> Settings:
    """Get cached application settings.

    Returns the same Settings instance throughout the application lifecycle.
    Uses functools.cache for thread-safe singleton behavior.
    """
    return Settings()

Usage:

from backend.core import get_settings

settings = get_settings()
print(settings.database_url)

Environment Variables by Category¶

Database Configuration¶

Source: backend/core/config.py:313-344

Redis Configuration¶

Source: backend/core/config.py:346-405

Redis SSL/TLS Settings¶

Source: backend/core/config.py:408-439

Cache TTL Settings¶

Source: backend/core/config.py:728-765

AI Service Endpoints¶

All AI models (YOLO26, Florence-2, CLIP, enrichment) run inside one ai-gateway container on port 8090 and are addressed by path prefix. .env.example defaults:

In containers the same routes use http://ai-gateway:8090/... and NEMOTRON_URL=http://ai-llm:8091 (docker-compose.prod.yml, backend AI Gateway routes block).

AI Service Timeouts¶

Source: backend/core/config.py:1046-1100

Batch Processing¶

Source: backend/core/config.py:935-956

Fast Path Configuration¶

Source: docker-compose.prod.yml:485-487, backend/core/config.py:1757-1770

Application Settings¶

Source: backend/core/config.py:842-930

CORS Settings¶

Default CORS origins (see backend/core/config.py:884-894):

[
    # HTTPS origins for external browser access
    "https://localhost:8444",
    "https://127.0.0.1:8444",
    "https://0.0.0.0:8444",
    # Internal container communication (HTTP within Docker network)
    "http://frontend:8080",
]

Set CORS_ORIGINS to your own hostnames for LAN access.

Nemotron Context Settings¶

Source: backend/core/config.py:1158-1227, .env.example:365

Feature Toggles¶

Source: backend/core/config.py:1573-1593

Nested Settings Classes¶

OrchestratorSettings¶

Container orchestrator configuration for Docker/Podman management.

Source: backend/core/config.py:114-295

TranscodeCacheSettings¶

Video transcoding cache configuration.

Source: backend/core/config.py:41-112

Configuration Validation¶

Pydantic validators ensure configuration correctness at startup.

URL Validation¶

AI service URLs are validated using AnyHttpUrl.

Source: backend/core/config.py:820-853

@field_validator("yolo26_url", "nemotron_url", mode="before")
@classmethod
def validate_ai_service_urls(cls, v: Any) -> str:
    """Validate AI service URLs using Pydantic's AnyHttpUrl validator."""
    url_str = str(v)
    try:
        validated_url = AnyHttpUrl(url_str)
        return str(validated_url).rstrip("/")
    except Exception as e:
        raise ValueError(f"Invalid AI service URL '{url_str}'...") from None

Grafana URL Validation¶

Grafana URLs include SSRF protection.

Source: backend/core/config.py:883-914

@field_validator("grafana_url", mode="before")
@classmethod
def validate_grafana_url_field(cls, v: Any) -> str:
    """Validate Grafana URL with SSRF protection (NEM-1077)."""
    # Allows relative paths like /grafana for nginx proxy
    if url_str.startswith("/"):
        return url_str
    return validate_grafana_url(url_str)

Environment Variable Cascade¶

The configuration system follows a clear precedence hierarchy where environment variables override file-based settings, enabling flexible deployment across different environments.

Environment Files¶

Example .env File¶

# Database
DATABASE_URL=postgresql+asyncpg://security:password@localhost:5432/security  # pragma: allowlist secret

# Redis
REDIS_URL=redis://localhost:6379/0
REDIS_PASSWORD=

# AI Services (Docker — single ai-gateway container)
YOLO26_URL=http://ai-gateway:8090/yolo26
NEMOTRON_URL=http://ai-llm:8091
FLORENCE_URL=http://ai-gateway:8090/florence
CLIP_URL=http://ai-gateway:8090/clip
ENRICHMENT_URL=http://ai-gateway:8090/enrichment
ENRICHMENT_LIGHT_URL=http://ai-gateway:8090/enrich-lt

# Batch Processing
BATCH_WINDOW_SECONDS=90
BATCH_IDLE_TIMEOUT_SECONDS=30

# Detection
DETECTION_CONFIDENCE_THRESHOLD=0.5
FAST_PATH_ENABLED=false

# Retention
RETENTION_DAYS=30

# Environment
ENVIRONMENT=development
DEBUG=false

Settings Access Pattern¶

from backend.core import get_settings

# In route handlers
@router.get("/example")
async def example_endpoint():
    settings = get_settings()
    return {"batch_window": settings.batch_window_seconds}

# In services
class MyService:
    def __init__(self):
        self._settings = get_settings()
        self._timeout = self._settings.ai_health_timeout

# Type hints for IDE support
from backend.core.config import Settings

def configure_client(settings: Settings) -> None:
    url = settings.yolo26_url

Configuration Best Practices¶

1. Never hardcode values - Use settings for all configurable values
2. Validate early - Pydantic validates at startup, fail fast on bad config
3. Document defaults - Every Field should have a description
4. Use appropriate types - Field constraints (ge, le, gt, lt) catch invalid values
5. Environment-specific - Use different .env files for dev/staging/prod

Related Documentation¶

• Deployment Topology - Container environment variables
• Design Decisions - Why these configuration choices
• Environment Reference - Complete variable list