EZ-Homelab/wiki/System-Architecture.md

System Architecture

Overview

The EZ-Homelab implements a layered, production-ready architecture designed for reliability, security, and ease of management. The system is built around Docker containers orchestrated through Traefik reverse proxy with Authelia SSO authentication.

Core Principles

1. Infrastructure as Code

• All services defined in Docker Compose files
• File-based configuration (AI-manageable)
• Version-controlled infrastructure
• Reproducible deployments

2. Security First

• Default Deny: All services start with Authelia SSO protection
• Explicit Bypass: Only media apps (Plex, Jellyfin) bypass SSO for app compatibility
• VPN Routing: Download services route through Gluetun VPN client
• Wildcard SSL: Single certificate covers all subdomains

3. Layered Architecture

┌─────────────────┐
│   Dashboards    │  ← User Interface Layer
│ (Homepage, UI)  │
└─────────────────┘
        │
┌─────────────────┐
│ Infrastructure  │  ← Management Layer
│ (Dockge, Auth)  │
└─────────────────┘
        │
┌─────────────────┐
│    Core Stack   │  ← Foundation Layer
│ (DNS, Proxy, VPN)│
└─────────────────┘

Component Architecture

Core Infrastructure Layer

The foundation that everything else depends on:

• DuckDNS: Dynamic DNS with Let's Encrypt DNS challenge
• Traefik: Reverse proxy with automatic HTTPS termination
• Authelia: SSO authentication with file-based user database
• Gluetun: VPN client for secure download routing
• Sablier: Lazy loading service for resource efficiency

Service Categories

Infrastructure Services

• Management: Dockge (primary), Portainer (secondary)
• Monitoring: Dozzle (logs), Glances (system), Pi-hole (DNS)
• Security: Authelia (SSO), VPN routing via Gluetun

Media Services

• Streaming: Plex, Jellyfin (with app compatibility bypass)
• Automation: Sonarr, Radarr, Prowlarr (*Arr stack)
• Downloads: qBittorrent (VPN-routed)

Productivity & Collaboration

• File Sync: Nextcloud with MariaDB
• Version Control: Gitea with PostgreSQL
• Documentation: BookStack, DokuWiki, MediaWiki
• Communication: Various collaboration tools

Home Automation

• Core: Home Assistant with database
• Development: ESPHome, Node-RED
• Connectivity: Mosquitto (MQTT), Zigbee2MQTT
• Surveillance: MotionEye

Monitoring & Observability

• Metrics: Prometheus, Node Exporter, cAdvisor
• Visualization: Grafana with Loki logging
• Alerting: Alertmanager, Uptime Kuma

Network Architecture

Docker Networks

• traefik-network: Primary network for all web-facing services
• homelab-network: Internal service communication
• dockerproxy-network: Secure Docker socket access

Routing Patterns

• Traefik Labels: Declarative routing configuration
• Authelia Middleware: SSO protection with bypass rules
• VPN Routing: network_mode: "service:gluetun" for downloads

Port Management

• External Ports: Only 80/443 exposed (Traefik)
• Internal Ports: Services communicate via Docker networks
• VPN Ports: Download services mapped through Gluetun

Storage Strategy

Configuration Storage

• Location: /opt/stacks/{stack-name}/config/
• Purpose: Application configuration and settings
• Backup: Included in backup strategy

Data Storage

• Small Data: Named Docker volumes (< 50GB)
• Large Data: External mounts /mnt/media, /mnt/downloads
• Databases: Containerized with persistent volumes

Backup Architecture

• Primary: Restic + Backrest for comprehensive backups
• Secondary: Service-specific backup tools (Duplicati)
• Strategy: 3-2-1 rule (3 copies, 2 media types, 1 offsite)

Security Model

Authentication Layers

1. Network Level: Firewall rules and VPN routing
2. Application Level: Authelia SSO with 2FA support
3. Service Level: Individual service authentication

Access Control

• Default Protected: All services require authentication
• Bypass Rules: Configured in Authelia for specific domains
• VPN Enforcement: Download traffic routed through VPN

Certificate Management

• Wildcard Certificates: *.yourdomain.duckdns.org
• Automatic Renewal: Traefik handles Let's Encrypt
• DNS Challenge: DuckDNS token-based validation

Deployment Model

Automated Setup

1. System Preparation: setup-homelab.sh

   • Docker installation
   • System configuration
   • Authelia secrets generation

2. Service Deployment: deploy-homelab.sh

   • Core stack deployment
   • Infrastructure services
   • Dashboard configuration

Management Interface

• Primary: Dockge web UI at dockge.yourdomain.duckdns.org
• Secondary: Portainer for advanced container management
• AI Integration: File-based configuration for AI assistance

Scalability & Performance

Resource Management

• Limits: Configured per service based on requirements
• Reservations: Guaranteed minimum resources
• Monitoring: System resource tracking

Service Categories by Resource Usage

• Lightweight: DNS, monitoring, authentication
• Standard: Web applications, dashboards
• Heavy: Media servers, databases
• Specialized: GPU-enabled services, high-I/O applications

Maintenance & Operations

Update Strategy

• Automated: Watchtower for container updates
• Manual: Service-specific update procedures
• Testing: Validation before production deployment

Monitoring & Alerting

• System: Glances, Prometheus, Grafana
• Services: Health checks and log aggregation
• Uptime: Uptime Kuma for external monitoring

Backup & Recovery

• Automated: Scheduled backups with Restic
• Manual: On-demand backups via Backrest UI
• Testing: Regular backup validation and restore testing

AI Integration

Copilot Instructions

• File-Based: All configuration in editable files
• Documentation: Comprehensive guides for AI assistance
• Templates: Ready-to-use configuration templates

Management Patterns

• Declarative: Define desired state in YAML
• Automated: Scripts handle complex deployment logic
• Validated: Health checks and verification steps

This architecture provides a robust, secure, and maintainable foundation for a production homelab environment. c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\System-Architecture.md