EZ-Homelab/docs/multi-server-deployment.md

Multi-Server Deployment with On-Demand Services

Overview

This guide explains the current multi-server architecture where:

• Core Server: Handles external traffic (ports 80/443); runs DuckDNS, Traefik (multi-provider), Authelia
• Additional Servers: Run Sablier (lazy loading) with direct port exposure; no local Traefik
• Manual Routing: Core Traefik routes to IP:PORT combinations via YAML configuration files
• Independent Management: Each server manages its own containers with lazy loading

Note

: This document describes the current simplified architecture. Additional servers are "headless" - they expose ports directly without local reverse proxy.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         CORE SERVER                              │
│  ┌────────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
│  │  DuckDNS   │  │ Traefik  │  │ Authelia │  │ Core Services │ │
│  │ (SSL DNS)  │  │ (multi-  │  │  (SSO)   │  │   (local)     │ │
│  │            │  │ provider)│  │          │  │               │ │
│  └────────────┘  └────┬─────┘  └──────────┘  └──────────────┘ │
│                       │                                          │
│          ┌──────────────┼──────────────┐                        │
│          │  Routes:     │              │                        │
│          │  • Local     │  (labels)    │                        │
│          │  • Remote    │  (YAML files)│                        │
└──────────┼──────────────┼──────────────┼────────────────────────┘
           │              │              │
    Ports  │  HTTP/HTTPS  │              │
    80/443 │              │              │
           ▼              ▼              ▼
    ┌─────────────────────────────────────────┐
    │       ADDITIONAL SERVER (e.g., Pi)      │
    │  ┌──────────┐  ┌───────┐  ┌──────────┐ │
    │  │ Sablier  │  │ Media │  │ Exposed  │ │
    │  │ (lazy    │  │ Apps  │  │ Ports    │ │
    │  │ loading) │  │       │  │ 5001,    │ │
    │  └──────────┘  └───────┘  │ 8085...  │ │
    └────────────────────────────┼──────────┘
                                 │
                    Direct port access
                    (no local reverse proxy)

Deployment Process

Step 1: Deploy Core Server

On the core server, run ez-homelab.sh

• Use Option 1 to Install Prerequisites
• Then Option 2 to Deploy Core Server

This deploys: DuckDNS, Traefik(core), Authelia, Dashboards & Infrastructure

From Dockge you can start/stop any of the stacks or containers.

Port Forwarding:

• Forward ports 80 & 443 from your router
• Only this server requires port forwarding

Step 2: Deploy Additional Server

On the additional server, run ez-homelab.sh

• Use Option 1 to Install Prerequisites
• Then Option 3 to Deploy Additional Server

This deploys: Sablier (lazy loading), Dashboards & Infrastructure

From Dockge you can start/stop any of the stacks or containers.

No Port Forwarding Required:

• Services are accessed through core server
• Additional servers are "headless" - no external ports needed

How It Works

Traffic Flow

1. User accesses https://sonarr.yourdomain.duckdns.org
2. Core Traefik receives request:
   • Checks Authelia for authentication (SSO)
   • Routes to additional server: http://192.168.1.100:8989 (via YAML config)
3. Additional server receives direct HTTP request:
   • Service container receives request on exposed port
   • If stopped, Sablier starts the container
   • Shows loading page while container starts
4. Service responds directly back to core Traefik, then to user

Service Registration

When you deploy an additional server:

1. Services are deployed with exposed ports (no Traefik labels)
2. Core server creates YAML route files pointing to IP:PORT
3. Core Traefik loads routes automatically
4. Services become accessible at https://servicename.hostname.yourdomain.duckdns.org

Key Benefits

• Simplified Architecture: No local Traefik on additional servers
• Direct Port Access: Services expose ports directly (no reverse proxy overhead)
• Centralized Access: All services accessed through one domain
• Unified SSO: Authelia on core server protects all services
• Local Lazy Loading: Sablier manages containers on each server independently

Performance Considerations

• Latency: Direct routing (core → service) minimizes hops
• Resource Usage: Additional servers run only Sablier (~50MB) - no Traefik needed
• Scalability: Can add unlimited additional servers without complexity
• Network: Internal 1Gbps+ recommended between servers
• Deployment Speed: Additional servers deploy in ~2 minutes (vs 5-10 with local Traefik)