kelin
013bdb969d
Major improvements to environment variable management: 1. Added .env.example files for ALL stacks - Each stack now has its own .env.example with only required variables - Variables include comments explaining their purpose - Examples: core, dockge, infrastructure, dashboards, arcane, media, media-management, transcoders, monitoring, sablier, utilities, productivity, wikis, vpn, homeassistant, alternatives 2. Created .env.global generation - Generates /opt/stacks/.env.global with all variables - Strips comments and blank lines for clean output - Available to all stacks for reference 3. Improved variable replacement strategy - Variable replacement now ONLY targets labels and x-dockge sections in docker-compose files - Configuration files (traefik, authelia) still get full variable replacement - Uses Python script for precise section detection - Preserves environment variables and volume mounts as-is 4. New deployment approach - Each stack copies .env.example to .env - Values populated from main ~/EZ-Homelab/.env file - No more manual sed commands to remove unused variables - Consistent approach across all deployment functions 5. Updated deployment functions - deploy_dockge, deploy_core, deploy_infrastructure, deploy_dashboards, deploy_arcane, deploy_sablier_stack - All now use process_stack_env() for clean .env handling - All use updated localize_yml_file() for targeted variable replacement Benefits: - Clean, minimal .env files for each stack - No unnecessary variables or comments in deployed .env files - Variables in compose files preserved for Docker Compose to handle - Easier to understand what each stack needs - Uniform deployment approach across all stacks
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