Nexus Icon

Nexus: Infrastructure Platform

Nexus is the single physical host running Ubuntu Server LTS that powers the entire HALO ecosystem. Every containerized service—from Traefik and PostgreSQL to Home Assistant and Frigate—runs on this infrastructure platform. Nexus provides Docker orchestration, network isolation, data persistence, and serves as the central coordination point for all HALO operations.

Purpose and Scope

Nexus is the infrastructure backbone where all backend services converge. Its primary responsibilities include:

Service Orchestration: Managing Docker container lifecycle, dependency ordering, health monitoring, and automated restarts through Watchtower.

Data Persistence: Providing PostgreSQL for relational data storage with schema-per-service isolation, ensuring data integrity and simplified backup operations.

Ingress & Routing: Operating Traefik as the single gateway for all HTTP/HTTPS traffic, handling TLS termination, service discovery, and routing to backend services.

Workflow Automation: Hosting n8n workflow engine with Redis-backed distributed workers for coordinating multi-system operations and event-driven automation.

Message Brokering: Running Mosquitto MQTT broker for lightweight real-time messaging between Home Assistant, Frigate, Zigbee2MQTT, and n8n workflows.

Device Automation: Providing Node-RED for low-latency reactive automation and device-level event processing.

Observability: Hosting Grafana for metrics visualization, dashboards, and system health monitoring.

Network Isolation: Implementing Docker networks (frontnet, appnet, dbnet) ensuring services communicate only through intended channels.

The system is designed for local-first operation where all core functionality works without internet connectivity. Cloud services are used only for enhancement features.

Core Services

Traefik - Ingress Proxy

Traefik serves as the single entry point for all web traffic entering HALO. Running on the frontnet Docker network, it provides:

Automatic Service Discovery: Detects containers through Docker labels, eliminating manual configuration
TLS Termination: Handles HTTPS certificates and encryption, presenting HTTP to backend services
Path-Based Routing: Routes requests to appropriate services based on URL paths and hostnames
Load Balancing: Distributes traffic across multiple container instances when scaled
Middleware Support: Request transformation, authentication, rate limiting, and header manipulation

Traefik continuously monitors Docker for container changes, automatically updating routing rules as services start or stop.

Access: https://halo.local (dashboard), all services proxied through Traefik

Configuration: Service routing defined via Docker labels in compose files

PostgreSQL - Shared Database

PostgreSQL 16.4 provides centralized relational database services for all HALO components. Running on the dbnet network with health checks and volume persistence, it uses schema-based isolation:

Home Assistant: Device states, automation history, sensor data
n8n: Workflow definitions, execution history, credentials
Omnia API: Widget configurations, user profiles, dashboard layouts
Grafana: Dashboard definitions, alert configurations

This shared-instance approach simplifies backup operations while maintaining logical separation between services.

Access: postgres-db:5432 (internal dbnet only)

Configuration: nexus/compose/postgres.yml

Redis - Message Broker

Redis provides in-memory data structures for pub/sub messaging, caching, and queue management. Critical for n8n distributed worker architecture, Redis enables:

Queue Workers: Background job processing for long-running workflows
Session Storage: Fast session state for web applications
Pub/Sub Messaging: Real-time event distribution between services
Caching Layer: Temporary data storage reducing database load

Access: redis:6379 (internal appnet only)

Configuration: nexus/compose/redis.yml

Mosquitto - MQTT Broker

Mosquitto MQTT broker handles lightweight messaging for device integrations. All Home Assistant, Frigate, and Zigbee2MQTT communication flows through MQTT topics:

Device Events: Zigbee sensors, switches, and lights publish state changes
Camera Events: Frigate publishes object detection and motion events
Automation Triggers: Home Assistant automations subscribe to MQTT topics
n8n Integration: Workflows react to MQTT messages for event-driven automation

MQTT’s publish-subscribe model enables loose coupling between services, allowing components to react to events without direct dependencies.

Access: mosquitto:1883 (internal appnet only)

Configuration: nexus/compose/mosquitto.yml

n8n - Workflow Engine

n8n provides visual workflow automation with distributed worker architecture. The main container serves the web UI while Redis-backed workers process long-running tasks:

Multi-System Integration: Connects Home Assistant, Frigate, Apollo, Omnia API
Event-Driven Automation: Reacts to webhooks, MQTT messages, scheduled triggers
Data Transformation: Chains API calls with conditional logic and data mapping
Retry Logic: Handles failures with exponential backoff and circuit breakers

Workflows provide the intelligent orchestration layer connecting user actions in Omnia to device control in Home Assistant and AI reasoning in Apollo.

Access: https://halo.local/n8n (proxied through Traefik)

Configuration: nexus/compose/n8n.yml

Node-RED - Device Automation

Node-RED delivers low-latency reactive automation for time-sensitive device control. While n8n handles complex multi-system workflows, Node-RED focuses on immediate response to device events:

MQTT Processing: Subscribes to device topics and triggers instant responses
Device Coordination: Coordinates multi-device scenes with precise timing
Fallback Logic: Provides automation continuity if n8n workflows are delayed
Custom Integrations: JavaScript-based custom logic for specialized use cases

Access: https://halo.local/node-red (proxied through Traefik)

Configuration: nexus/compose/node-red.yml

Grafana - Metrics & Dashboards

Grafana provides metrics visualization and monitoring dashboards. Pulling data from PostgreSQL, it displays:

System Metrics: CPU, memory, disk usage, network throughput
Service Health: Container status, restart counts, uptime tracking
Device Analytics: Sensor trends, automation trigger frequencies
Performance Monitoring: API response times, workflow execution duration

Access: https://halo.local/grafana (proxied through Traefik)

Configuration: nexus/compose/grafana.yml

Watchtower - Container Updates

Watchtower monitors Docker container images and automatically updates running containers when new versions are available:

Automated Updates: Pulls latest images and recreates containers
Scheduled Checks: Configurable update frequency (daily, weekly)
Notifications: Sends alerts on successful or failed updates
Rollback Support: Can revert to previous image on startup failures

Access: Background service (no user interface)

Configuration: nexus/compose/watchtower.yml

HALO Application Services

Home Assistant - Device Control

Home Assistant runs as a containerized service on Nexus, managing all smart-home devices, scenes, and automations. Configuration files are version-controlled in configs/home-assistant/.

Integrations:

Zigbee2MQTT for Zigbee device coordination
MQTT for event publishing and subscription
Frigate for camera integration
Node-RED for low-latency automation

Access: https://halo.local/ha (proxied through Traefik)

Configuration: configs/home-assistant/ + nexus/compose/home-assistant.yml

Omnia (API) - Dashboard Backend

Omnia API manages widget configurations, user profiles, and dashboard layouts. Running as a containerized service on Nexus, it provides:

Widget manifest serving and version management
User authentication and profile storage
Dashboard layout persistence per device
Backend data for widgets (tasks, notes, calendars)

Access: https://halo.local/api/omnia (proxied through Traefik)

Configuration: services/omnia-api/ + nexus/compose/omnia-api.yml

Frigate - AI Camera System

Frigate provides AI-powered security camera monitoring with real-time object detection. Running as a containerized service on Nexus with Google Coral TPU access, it processes video feeds, identifies objects, and publishes events to MQTT.

Hardware Requirements:

Google Coral TPU (USB) attached to Nexus host
Reolink cameras accessible over network

Access: https://halo.local/frigate (proxied through Traefik)

Configuration: configs/frigate/ + nexus/compose/frigate.yml

Zigbee2MQTT - Zigbee Integration

Zigbee2MQTT bridges Zigbee devices to MQTT and Home Assistant. Running as a containerized service with Sonoff Zigbee 3.0 USB Dongle Plus attached to Nexus:

Supported Devices: Sensors, switches, lights, locks, and other Zigbee 3.0 devices

Access: https://halo.local/zigbee (proxied through Traefik)

Configuration: configs/zigbee2mqtt/ + nexus/compose/zigbee2mqtt.yml

Front-End Applications

Omnia (Screen) - Dashboard UI

The Omnia React application is served as static files through Traefik. Built files are deployed to a volume mounted in the Traefik container, enabling zero-downtime updates.

Deployment: apps/omnia-ui/dist/ → Traefik static file serving

Access: https://halo.local (root path)

Grafana UI - Metrics Visualization

Grafana’s web interface provides access to dashboards, alerts, and data exploration tools.

Access: https://halo.local/grafana

Home Assistant UI - Smart-Home Interface

Home Assistant’s Lovelace interface is proxied through Traefik for device control and automation management.

Access: https://halo.local/ha

External & Connected Hardware

Apollo - AI & LLM Workloads

Apollo is separate hardware, not a container on Nexus. This independent system runs AI and large language model workloads with dedicated GPU resources.

Connection: Apollo exposes APIs accessible from Nexus containers over the local network

Integration: n8n workflows, Omnia widgets, and automation logic call Apollo APIs for AI reasoning

Google Coral TPU

USB-attached tensor processing unit providing hardware acceleration for Frigate’s object detection models.

Connection: USB passthrough to Frigate container

Performance: 400+ FPS detection rate with minimal CPU load

Sonoff Zigbee 3.0 USB Dongle Plus

Zigbee coordinator enabling communication with Zigbee devices.

Connection: USB passthrough to Zigbee2MQTT container

Network: Supports up to 100 direct children + unlimited routed devices

Network Architecture

Nexus implements three-tier network isolation through Docker networks:

frontnet (Public Network)

Only Traefik connects to frontnet. All external traffic enters through this single point, enabling centralized access control and monitoring.

Connected Services: Traefik only

appnet (Application Network)

Services requiring inter-service communication connect to appnet. This includes all application services that need to call each other’s APIs.

Connected Services: Traefik, n8n, Node-RED, Home Assistant, Omnia API, Frigate, Zigbee2MQTT, Mosquitto, Redis

dbnet (Database Network)

Only services requiring database access connect to dbnet. This isolation prevents compromised application services from directly accessing persistent data.

Connected Services: PostgreSQL, n8n, Omnia API, Home Assistant, Grafana

Directory Structure

halo/
└── nexus/
    ├── compose/              # Docker Compose service definitions
    │   ├── networks.yml      # Network definitions
    │   ├── traefik.yml       # Traefik ingress proxy
    │   ├── postgres.yml      # PostgreSQL database
    │   ├── redis.yml         # Redis message broker
    │   ├── mosquitto.yml     # MQTT broker
    │   ├── n8n.yml           # n8n workflow engine + workers
    │   ├── node-red.yml      # Node-RED automation
    │   ├── grafana.yml       # Grafana dashboards
    │   ├── watchtower.yml    # Container update monitor
    │   ├── home-assistant.yml # Home Assistant container
    │   ├── frigate.yml       # Frigate AI cameras
    │   └── zigbee2mqtt.yml   # Zigbee integration
    ├── traefik/              # Traefik configuration
    │   ├── traefik.yml       # Main Traefik config
    │   └── dynamic/          # Dynamic configuration
    ├── scripts/              # Deployment and management
    │   └── deploy.ps1        # PowerShell deployment automation
    └── env/                  # Environment variable templates
        └── prod.env.sample   # Example configuration

Integration Pattern

The Nexus architecture follows a hub-and-spoke model:

Traefik fronts all web services, handling ingress and TLS
Home Assistant integrates with Frigate, Zigbee2MQTT, MQTT, and Node-RED
n8n coordinates workflows across PostgreSQL, Home Assistant, Omnia API, and Apollo (external)
Redis enables distributed worker processing for n8n
Grafana pulls metrics from PostgreSQL and system monitoring
Watchtower handles automated container updates and restarts

Deployment Process

Services are deployed using PowerShell scripts that handle Docker Compose orchestration:

# Deploy core infrastructure
cd nexus
.\scripts\deploy.ps1 -Files @("compose\networks.yml", "compose\traefik.yml", "compose\postgres.yml")

# Deploy messaging and workflow
.\scripts\deploy.ps1 -Files @("compose\redis.yml", "compose\mosquitto.yml", "compose\n8n.yml")

# Deploy HALO services
.\scripts\deploy.ps1 -Files @("compose\home-assistant.yml", "compose\frigate.yml", "compose\zigbee2mqtt.yml")

# Deploy monitoring
.\scripts\deploy.ps1 -Files @("compose\grafana.yml", "compose\watchtower.yml")

The deployment script:

Loads environment variables from nexus/env/ directory
Sets Docker Compose project name to “nexus” for consistent naming
Executes docker compose up -d with specified files
Verifies service health through Docker health checks

Hardware Requirements

Minimum Configuration:

4-core CPU (Intel i5 or equivalent)
16GB RAM
256GB SSD storage
Gigabit Ethernet

Recommended Configuration:

6-core CPU (Intel i7-8750H or equivalent)
32GB RAM
512GB NVMe (OS and containers) + 1TB SSD (media and recordings)
Gigabit Ethernet

The current Nexus deployment runs on a mini-PC with Intel i7-8750H, 32GB RAM, NVMe + SATA SSD storage.

Security Considerations

Nexus implements multi-layer security:

Network Isolation: Docker networks prevent unauthorized inter-service communication
Ingress Control: Traefik provides single entry point with TLS, authentication middleware
Database Access: Limited to services explicitly requiring it through dbnet connection
Secrets Management: Environment variables stored in .env files excluded from version control
Local-First: No external dependencies for core functionality reduces attack surface
Automated Updates: Watchtower keeps containers patched against vulnerabilities

Monitoring and Maintenance

Operational visibility through:

Container Health Checks: Docker monitors service availability, triggers automatic restarts
Traefik Access Logs: Request logs track API usage and identify errors
n8n Execution History: Workflow execution logs show success/failure status
Grafana Dashboards: Real-time system metrics and service health visualization
PostgreSQL Logs: Database connection diagnostics and slow query identification

For detailed container reference information, see Container Reference.

For information on developing n8n workflows, see n8n Workflows.

For hardware specifications, see Nexus Hardware.

For deployment portability and migration strategies, see Portability & Migrations.

For ingress routing and authentication, see Ingress & Identity.

For backup strategies and data management, see Data & Backups.

Nexus is the invisible engine behind HALO. If the interface is what you see, Nexus is the system that thinks, connects, and acts behind the scenes.