kelin/EZ-Homelab

Fork 0

Files

Kelin 30143d5f75 Update documentation files with recent tweaks

2026-02-08 18:42:16 -05:00

10 KiB

Raw Permalink Blame History

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/ | 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/ | 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/ | 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/ | 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/ | 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/ | service-docs/gluetun.md

How Services Get Added

The AI Way (Recommended)

Tell the AI: "Add Plex to my media stack"
AI Creates: Docker Compose file with proper configuration
AI Configures: Traefik routing, Authelia protection, resource limits
AI Deploys: Service goes live with HTTPS and SSO
AI Updates: Homepage dashboard automatically

Manual Way

Find Service: Choose from 50+ pre-configured services
Upload to Dockge: Use the web interface
Configure: Set environment variables and volumes
Deploy: Click deploy and wait
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

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

See 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

Network Level: Firewall blocks unauthorized access
SSL/TLS: All traffic encrypted with valid certificates
Authentication: Authelia protects admin interfaces
Authorization: User roles and permissions
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