Wiki major update
updated with recent documentation
This commit is contained in:
kelinfoxy
191
wiki/System-Architecture.md
Normal file
191
wiki/System-Architecture.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# System Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The AI-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.</content>
|
||||
<parameter name="filePath">c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\System-Architecture.md
|
||||
Reference in New Issue
Block a user