Operator Hub¶

Deploy, configure, and maintain Home Security Intelligence.

This hub is for sysadmins, DevOps engineers, and technically savvy users who deploy and maintain the system. For end-user documentation, see the User Hub. For development and contribution, see the Developer Hub.

Quick Navigation¶

Quick Deploy¶

Estimated deployment time: 30-45 minutes (including model downloads)

# 1. Clone and setup
git clone https://github.com/mikesvoboda/nemotron-v3-home-security-intelligence.git
cd nemotron-v3-home-security-intelligence
python setup.py         # Generates .env with secure passwords

# 2. Download AI models (~33GB total; Nemotron alone is 15GB)
./ai/download_models.sh

# 3. Start services
podman compose -f docker-compose.prod.yml up -d

# 4. Verify
curl http://localhost:8000/api/system/health/ready

System Requirements¶

AI VRAM Usage (Production):

Always-Loaded Core Services¶

Florence-2, YOLO26 and the embedding models all run inside the single ai-gateway container (host port AI_GATEWAY_PORT, default 8090) through routers /yolo26, /florence, /clip, /enrichment and /enrich-lt.

VRAM Tiers¶

Supported GPUs: RTX 30/40 series, RTX A-series, Tesla/V100/A100

Service Architecture¶

Camera uploads --> backend FileWatcher --> detection_queue
  --> YOLO26 via ai-gateway (8090/yolo26) --> detections (DB)
  --> batching + enrichment via ai-gateway (8090/enrichment, /enrich-lt)
  --> Nemotron (8091) --> events (DB)
  --> WebSocket dashboard

Deployment Architecture Diagram¶

The following diagram shows the complete container topology, network connections, and data flows:

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#3B82F6',
    'primaryTextColor': '#FFFFFF',
    'primaryBorderColor': '#60A5FA',
    'secondaryColor': '#A855F7',
    'tertiaryColor': '#009688',
    'background': '#121212',
    'mainBkg': '#1a1a2e',
    'lineColor': '#666666'
  }
}}%%
flowchart TB
    subgraph External["External Access"]
        Browser["Browser<br/>host 8080 HTTP / 8444 HTTPS"]
        Camera["Foscam Cameras<br/>FTP Upload"]
    end

    subgraph Frontend["Frontend Layer"]
        FE["frontend<br/>nginx container 8080 HTTP / 8443 HTTPS<br/>Proxies /api, /ws, /grafana/"]
    end

    subgraph Backend["Backend Layer"]
        BE["backend<br/>FastAPI :8000"]
    end

    subgraph AI["AI Services (GPU)"]
        GW["ai-gateway :8090<br/>Triton: /yolo26 /florence /clip<br/>/enrichment /enrich-lt"]
        LLM["ai-llm<br/>Nemotron llama.cpp :8091"]
    end

    subgraph Data["Data Layer"]
        PG[("postgres<br/>PostgreSQL :5432")]
        RD[("redis<br/>Redis :6379")]
    end

    subgraph Monitoring["Monitoring Stack"]
        PROM["prometheus<br/>host 9090"]
        GRAF["grafana<br/>host 3002 · /grafana/ via frontend"]
        TEMPO["tempo<br/>:3200"]
        LOKI["loki<br/>:3100"]
        PYRO["pyroscope<br/>:4040"]
        ALLOY["alloy<br/>UI 12345"]
        AM["alertmanager<br/>:9093"]
        BB["blackbox-exporter<br/>:9115"]
        RE["redis-exporter<br/>:9121"]
        JE["json-exporter<br/>:7979"]
    end

    %% External connections
    Browser --> FE
    Camera --> BE

    %% Frontend proxies to Backend
    FE -->|"HTTP/WS /api /ws"| BE
    FE -->|"HTTP /grafana/"| GRAF

    %% Backend to Data
    BE -->|"asyncpg"| PG
    BE -->|"aioredis"| RD

    %% Backend to AI Services
    BE -->|"HTTP"| GW
    BE -->|"HTTP"| LLM

    %% Monitoring connections
    PROM --> BE
    PROM -->|"ai-gateway:8002"| GW
    PROM --> LLM
    PROM --> RE
    PROM --> JE
    PROM --> BB
    PROM --> AM
    GRAF --> PROM
    GRAF --> LOKI
    GRAF --> TEMPO
    GRAF --> PYRO
    ALLOY --> LOKI
    ALLOY --> PYRO
    ALLOY -->|"OTLP"| TEMPO
    BE -->|"OTLP"| ALLOY

MQTT Integration¶

The backend publishes detection events to an MQTT broker, enabling integration with Home Assistant, Node-RED, and custom automation scripts. Home Assistant auto-discovery is supported via the homeassistant/discovery topic.

flowchart TB
    subgraph Backend["Backend Services"]
        PUB["MQTT Publisher"]
        CMD["Command Handler"]
        HA["Home Assistant<br/>Auto-Discovery"]
    end
    subgraph Broker["MQTT Broker"]
        T1["events/detections"]
        T2["commands/#"]
        T3["homeassistant/discovery"]
    end
    subgraph External["External Consumers"]
        HASS["Home Assistant"]
        NR["Node-RED"]
        CUSTOM["Custom Scripts"]
    end
    PUB --> T1
    T2 --> CMD
    HA --> T3
    T1 --> HASS & NR & CUSTOM
    T3 --> HASS
    HASS -->|Commands| T2

Network: All services connect via the security-net bridge network for internal DNS resolution.

Volume Mounts:

Ports Reference¶

Host ports come from .env; every service except frontend binds 127.0.0.1 only. Access Grafana and the API through the frontend nginx proxy for anything off-host.

docker-compose.prod.yml defines 21 services; two are behind profiles (vllm, gpu-rootful), so a default up -d starts 19. The 5173 Vite port in .env.example (FRONTEND_PORT) is unused by the compose file — the Vite dev server listens on HTTPS 8444 (see frontend/vite.config.ts).

Quick Commands¶

Service Management¶

# Start all services (production)
podman compose -f docker-compose.prod.yml up -d

# Stop all services
podman compose -f docker-compose.prod.yml down

# View logs
podman compose -f docker-compose.prod.yml logs -f
podman compose -f docker-compose.prod.yml logs -f backend

# Restart a service
podman compose -f docker-compose.prod.yml restart backend

Health Checks¶

# System health
curl http://localhost:8000/api/system/health/ready

# Full health with circuit breakers
curl http://localhost:8000/api/system/health/full

# AI services
curl http://localhost:8090/health            # ai-gateway (YOLO26/Florence/CLIP/enrichment)
curl http://localhost:8090/yolo26/health     # per-router health
curl http://localhost:8091/health            # Nemotron

# Database
podman compose -f docker-compose.prod.yml exec postgres pg_isready

# Redis
podman compose -f docker-compose.prod.yml exec redis redis-cli ping

GPU Management¶

# GPU status
nvidia-smi

# GPU memory usage
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

# Kill GPU processes (emergency)
fuser -k /dev/nvidia*

Detailed Guides¶

Deployment¶

• Complete Deployment Guide - Docker/Podman setup, compose files, GHCR images
• GPU Setup Guide - NVIDIA drivers, container toolkit, CDI
• AI Services Guide - YOLO26, Nemotron, optional services
• Deployment Modes - AI networking for different setups

Monitoring¶

• Monitoring Guide - Health checks, GPU metrics, DLQ
• Prometheus Alerting - Alert rules, Alertmanager
• Service Level Objectives - SLIs, SLOs, error budgets

Administration¶

• Administration Guide - Configuration, secrets, security
• Backup and Recovery - Database backup, disaster recovery
• Redis Setup - Authentication, persistence

Troubleshooting¶

Quick Diagnostics¶

# Comprehensive health check
curl http://localhost:8000/api/system/health/full | jq

# Container status
podman compose -f docker-compose.prod.yml ps

# Recent logs
podman compose -f docker-compose.prod.yml logs --tail=100 backend

# GPU availability
nvidia-smi

Common Issues¶

Getting Help¶

When reporting issues, collect:

# System health
curl http://localhost:8000/api/system/health | jq

# GPU info
nvidia-smi

# Container status
podman compose -f docker-compose.prod.yml ps

# Recent logs
podman compose -f docker-compose.prod.yml logs --tail=100 backend

See Also¶

• User Hub - End-user documentation
• Developer Hub - Development and contribution
• API Reference - REST and WebSocket APIs
• Architecture Overview - System design