# How Your EZ Homelab Works

This guide explains how all the components work together to create your homelab infrastructure. 

## Quick Overview

Your homelab is a **Docker-based infrastructure** that automatically:
- Provides secure HTTPS access to all services
- Manages user authentication and authorization
- Routes traffic intelligently
- Updates itself
- Backs up your data
- Monitors system health
- **Scales across multiple servers**

Everything runs in **containers** - like lightweight virtual machines - that are orchestrated by **Docker Compose** and managed through the **Dockge** web interface.

## Single-Server vs Multi-Server

EZ-Homelab supports two deployment architectures:

### Single Server
- All services run on one machine
- Traefik and Sablier manage local services only
- Simplest setup for homelab beginners
- Ideal for: Single desktop/server, all services in one place

### Multi-Server
- **Core Server**: Handles external traffic (ports 80/443), runs DuckDNS/Traefik/Authelia
- **Remote Servers**: Run their own Traefik/Sablier for local container management
- Unified domain access: All services through `service.yourdomain.com`
- Servers communicate via HTTP/HTTPS

**This guide covers both architectures**, with multi-server notes where relevant.

## Core Components

### 🏠 **Homepage Dashboard** (`https://homepage.yourdomain.duckdns.org`)
Your central hub for accessing all services. Think of it as the "start menu" for your homelab.
- **What it does**: Shows all your deployed services with quick links
- **AI Integration**: The AI can automatically add new services and configure widgets
- **Configuration**: [docker-compose/dashboards/](docker-compose/dashboards/) | [service-docs/homepage.md](service-docs/homepage.md)

### 🐳 **Dockge** (`https://dockge.servername.yourdomain.duckdns.org`)
Your primary management interface for deploying and managing services.
- **What it does**: Web-based Docker Compose manager
- **Stacks**: Groups services into logical units (media, monitoring, productivity)
- **One-Click Deploy**: Upload compose files and deploy instantly
- **Dockge Agents**: Deploy on core or remote servers from one interface
- **Configuration**: [docker-compose/dockge/](docker-compose/dockge/) | [service-docs/dockge.md](service-docs/dockge.md)

### 🔐 **Authelia** (`https://auth.yourdomain.duckdns.org`)
Your security gatekeeper that protects sensitive services.
- **What it does**: Single sign-on (SSO) authentication
- **Security**: Two-factor authentication, session management
- **Smart Bypass**: Bypasses auth for select apps (Plex, Jellyfin)
- **Multi-Server**: Core server only; protects all services across all servers
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/authelia.md](service-docs/authelia.md)

### 🌐 **Traefik** (`https://traefik.servername.yourdomain.duckdns.org`)
Your intelligent traffic director and SSL certificate manager.
- **What it does**: Reverse proxy that routes web traffic to the right services
- **SSL**: Automatically obtains and renews free HTTPS certificates
- **Labels**: Services on core server "advertise" themselves to Traefik via Docker labels
- **Multi-Server**: Remote servers use yaml (on the core server) only
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/traefik.md](service-docs/traefik.md)

### 🦆 **DuckDNS**
Your dynamic DNS service that gives your homelab a consistent domain name.
- **What it does**: Updates `yourdomain.duckdns.org` to point to your home IP
- **Integration**: Works with Traefik to get wildcard SSL certificates
- **Multi-Server**: Core server only (one domain for all servers)
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/duckdns.md](service-docs/duckdns.md)

### 🛡️ **Gluetun (VPN)**
Your download traffic protector.
- **What it does**: Routes torrent and download traffic through VPN
- **Security**: Prevents ISP throttling and hides your IP for downloads
- **Integration**: Download services connect through Gluetun's network
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/gluetun.md](service-docs/gluetun.md)

## How Services Get Added

### The AI Way (Recommended)
1. **Tell the AI**: "Add Plex to my media stack"
2. **AI Creates**: Docker Compose file with proper configuration
3. **AI Configures**: Traefik routing, Authelia protection, resource limits
4. **AI Deploys**: Service goes live with HTTPS and SSO
5. **AI Updates**: Homepage dashboard automatically

### Manual Way
1. **Find Service**: Choose from 50+ pre-configured services
2. **Upload to Dockge**: Use the web interface
3. **Configure**: Set environment variables and volumes
4. **Deploy**: Click deploy and wait
5. **Access**: Service is immediately available at `https://servicename.yourdomain.duckdns.org`

## Network Architecture

### Internal Networks (Per Server)
- **`traefik-network`**: All web-facing services connect here
- **`homelab-network`**: Internal service communication
- **`media-network`**: Media services (Plex, Jellyfin, etc.)
- **VPN Networks**: Download services route through Gluetun

### External Access

**Single Server:**
- **Port 80/443**: Only Traefik exposes these to the internet
- **Domain**: `*.yourdomain.duckdns.org` points to your home
- **SSL**: Wildcard certificate covers all subdomains automatically

**Multi-Server:**
- **Core Server Ports**: Only core forwards 80/443 to internet
- **Remote Servers**: No port forwarding needed; accessed through core
- **Traffic Flow**: Internet → Core Traefik → Service
- **SSL**: Core handles all SSL termination
- **Unified Domain**: `service.yourdomain.com` works for all servers

## Storage Strategy

### Configuration Files
- **Location**: `/opt/stacks/stack-name/config/`
- **Purpose**: Service settings, databases, user data
- **Backup**: Included in automatic backups

### Media & Large Data

>You may want additional drives for large downloads & media libraries

- **Location**: `/mnt/media/`, `/mnt/downloads/`
- **Purpose**: Movies, TV shows, music, downloads
- **Performance**: Direct mounted drives for speed

### Secrets & Environment
- **Location**: `.env` files in each stack directory
- **Security**: Never committed to git
- **Management**: AI can help update variables

## AI Features

### VS Code Integration
- **Copilot Chat**: Natural language commands for infrastructure management
- **File Editing**: AI modifies Docker Compose files, configuration YAML
- **Troubleshooting**: AI analyzes logs and suggests fixes
- **Documentation**: AI keeps docs synchronized with deployed services

### OpenWebUI (Future)
- **Web Interface**: Chat with AI directly in your browser
- **API Tools**: AI can interact with your services' APIs
- **Workflows**: Automated service management and monitoring
- **Status**: Currently in development phase

## Lazy Loading (Sablier)

Some services start **on-demand** to save resources:
- **How it works**: Service starts when you first access it
- **Benefits**: Saves RAM and CPU when services aren't in use
- **Configuration**: AI manages the lazy loading rules
- **Multi-Server**: Each server runs its own Sablier for LOCAL container management

## Multi-Server Architecture (Optional)

If you deploy across multiple servers:

### Core Server Responsibilities
- **External Traffic**: Only server with ports 80/443 forwarded
- **SSL Termination**: Handles all HTTPS certificates
- **SSO Gateway**: Authelia protects all services across servers
- **DNS Updates**: DuckDNS points domain to this server
- **Route Configuration**: Traefik YAML files route to remote servers

### Remote Server Responsibilities
- **Local Services**: Runs media, downloads, or specialized workloads
- **Local Management**: Own Traefik and Sablier instances
- **Internal Access**: Services listen on Docker networks only
- **Lazy Loading**: Sablier starts/stops containers locally

### Traffic Flow Example
```
User requests: https://sonarr.yourdomain.com
    ↓
1. Internet → Core Server (ports 80/443)
2. Core Traefik → Authelia (check login)
3. Core Traefik → Remote Server (http://192.168.1.100:8989)
4. Remote Traefik → Sablier (is service running?)
5. Remote Sablier → Starts Container (if needed)
6. Service Response → Back through chain to user
```

### Setup Process
1. **Core**: Deploy with `ez-homelab.sh` option 1 or 2
2. **Remote**: Deploy with `ez-homelab.sh` option 3 per server
3. **Configure**: Add external YAML files on core for remote services
4. **Access**: All services available through core domain

See [Ondemand-Remote-Services.md](Ondemand-Remote-Services.md) for detailed setup.

## Monitoring & Maintenance

### Built-in Monitoring
- **Grafana/Prometheus**: System metrics and dashboards
- **Uptime Kuma**: Service uptime monitoring
- **Dozzle**: Live container log viewing
- **Node Exporter**: Hardware monitoring

### Automatic Updates
- **Watchtower**: Updates Docker images automatically
- **Backrest**: Scheduled backups using Restic
- **Certificate Renewal**: SSL certificates renew automatically

## Security Model

### Defense in Depth
1. **Network Level**: Firewall blocks unauthorized access
2. **SSL/TLS**: All traffic encrypted with valid certificates
3. **Authentication**: Authelia protects admin interfaces
4. **Authorization**: User roles and permissions
5. **Container Security**: Services run as non-root users

### VPN for Downloads
- **Purpose**: Hide IP address for torrenting
- **Implementation**: Download containers route through VPN
- **Provider**: Surfshark (configurable)

## Scaling & Customization

### Adding Services

**Single Server:**
- **Pre-built**: [50+ services](services-overview.md) ready to deploy
- **Custom**: AI can create configurations for any Docker service
- **External Devices**: Proxy services on Raspberry Pi, NAS via Traefik YAML files

**Multi-Server:**
- **Remote Services**: Deploy on any server with Traefik labels
- **Core Routing**: Add external YAML file on core to route traffic
- **Unified Access**: All services appear under same domain
- **See**: [Ondemand-Remote-Services.md](Ondemand-Remote-Services.md) for patterns

### Resource Management
- **Limits**: CPU, memory, and I/O limits prevent resource exhaustion
- **Reservations**: Guaranteed minimum resources
- **GPU Support**: Automatic NVIDIA GPU detection and configuration