EZ-Homelab/docker-compose/core/README.md

Core Infrastructure Services

This directory contains the core infrastructure services that form the foundation of the homelab. These services should be deployed on the core server only and are critical for the operation of all other services across all servers.

Services

DuckDNS

• Purpose: Dynamic DNS service for domain resolution and wildcard SSL certificates
• Subdomain: Configurable via environment variables
• Token: Configured in environment variables
• SSL Certificates: Generates wildcard cert used by all services on all servers
• Deploy: Core server only

Traefik (v3)

• Purpose: Reverse proxy and SSL termination with multi-server routing
• Ports: 80 (HTTP), 443 (HTTPS), 8080 (Dashboard)
• Configuration: Located in traefik/config/traefik.yml
• Multi-Server: Discovers services on all servers via Docker providers
• SSL: Let's Encrypt with DNS-01 challenge (wildcard certificate)
• Dashboard: Available at configured domain
• Deploy: Core server only

Authelia (v4.37.5)

• Purpose: Single sign-on authentication service for all services across all servers
• Port: 9091 (internal)
• Access: Configured authentication domain
• Configuration: Located in authelia/config/
• Database: SQLite database in authelia/config/db.sqlite3
• Deploy: Core server only

Multi-Server Architecture

The core stack on the main server provides centralized services for the entire homelab:

Core Server:

• Receives all external traffic (ports 80/443 forwarded from router)
• Runs DuckDNS for domain management and SSL certificates
• Runs Authelia for centralized authentication
• Runs Sablier for lazyloading local containers
• Traefik lables route servies on the core server
• Traekif external-host-servername.yml defines routes for Remote Servers

Remote Server:

• Each container exposes ports
  • No port forwarding from router needed
• No Traefik lables
  • Traefik configured by an external-host yaml file on Core Server
• Runs Sablier for lazyloading local containers

Service Access:

• All services accessible via: https://service.yourdomain.duckdns.org
• Core Traefik routes to appropriate server (local or remote)
• Single wildcard SSL certificate used for all services
• Authelia provides SSO for all protected services

⚠️ Version Pinning & Breaking Changes

Authelia Version Pinning

Current Version: authelia/authelia:4.37.5

Breaking Changes Identified:

• Authelia v4.39.15+ has breaking configuration changes that are incompatible with the current setup
• Database schema changes may require migration or recreation
• Configuration file format changes may break existing setups

Action Taken:

• Pinned to v4.37.5 which is confirmed working
• Database recreated from scratch to ensure compatibility
• Configuration files verified and working

Upgrade Path:

• Test upgrades in a separate environment first
• Backup configuration and database before upgrading
• Check Authelia changelog for breaking changes
• Consider using Authelia's migration tools if available

Traefik Version Pinning

Current Version: traefik:v3

Notes:

• Traefik v3 is stable and working with current configuration
• Configuration format is compatible
• No breaking changes identified in current setup

Configuration Requirements

File Structure

core/
├── docker-compose.yml          # Main service definitions
├── .env                        # Environment variables
├── authelia/
│   ├── config/
│   |   ├── configuration.yml   # Authelia main config
│   |   └── notification.txt
|   └── secrets/
|       └── users_database.yml  # User credentials
├── duckdns/
│   └── config/                 # DuckDNS configuration
├── traefik/
│   ├── config/
│   │   └── traefik.yml         # Traefik static config
│   ├── dynamic/                # Dynamic configurations
│   │   ├── routes.yml
│   │   ├── sablier.yml
│   │   └── external-host-*.yml # Remote server routing
│   └── letsencrypt/
│       └── acme.json           # SSL certificates