9454b3862e
- Add DNS resolvers (1.1.1.1, 8.8.8.8) to traefik.yml for faster DNS challenge - Create wildcard-cert.yml to request *.kelinreij.duckdns.org certificate - Add comprehensive setup documentation for wildcard certificates - Update to use production Let's Encrypt email This configuration will automatically request a wildcard certificate covering all subdomains once the Let's Encrypt rate limit resets (Feb 13, 2026 at 21:33 UTC), eliminating the need for individual per-service certificates.
EZ-Homelab
Homelab infrastructure with automated SSL, SSO authentication, and VPN routing.
Deploy 50+ services through a file-based, AI-manageable architecture.
Plus Dockge for visual management of containers, and Homepage dashboard to easily access deployed services.
The easy way to get a homelab up and running securely
So simple anyone can do it in about an hour
🚀 Quick Start
Prerequisites
- Fresh Debian/Ubuntu server (or existing system)
- Root/sudo access
- Internet connection
- VS Code with GitHub Copilot (recommended for AI assistance)
Automated Setup
# Clone repository
git clone https://github.com/kelinfoxy/EZ-Homelab.git
cd EZ-Homelab
# Run the unified setup script (guided installation)
./scripts/ez-homelab.sh
Multi-Server Support:
- Core Server: Full deployment with ports 80/443 forwarded from router
- Remote Servers: Infrastructure-only setup (option 3 in script)
- Each server runs its own Traefik and Sablier for local container management
- Core server Traefik routes to all servers via Docker TLS providers
What the script does:
- Installs Docker and required system packages
- Guides you through configuration (domain, admin credentials, etc.)
- Deploys selected services based on your needs
- Sets up all stacks for Dockge management
Access your homelab:
- Dockge:
https://dockge.yourdomain.duckdns.org(primary management interface) - Homepage:
https://homepage.yourdomain.duckdns.org(service dashboard) - Authelia:
https://auth.yourdomain.duckdns.org(SSO login)
📚 Documentation
- Getting Started Guide - Step-by-step deployment and configuration
- Automated Setup - Guided installation with ez-homelab.sh script
- Manual Setup - Step-by-step manual installation
- Docker Guidelines - Service management patterns and best practices
- Services Reference - All 50+ available services
- Quick Reference - Command cheat sheet and troubleshooting
- Proxying External Hosts - Connect non-Docker services (Raspberry Pi, NAS, etc.)
- Multi-Server Setup - Deploy services across multiple servers
🚀 Quick Navigation
New to EZ-Homelab? → Getting Started Guide
Need Help Deploying? → Automated Setup
Want to Add Services? → Service Creation Guide
Having Issues? → Troubleshooting
Multi-Server Setup? → Remote Services Guide
Managing Services? → Dockge Dashboard at https://dockge.yourdomain.duckdns.org
Service Documentation
Individual service documentation is available in docs/service-docs/:
- Authelia - SSO authentication
- Traefik - Reverse proxy and SSL
- Sablier - Lazy loading for on-demand containers
- DuckDNS - Dynamic DNS
- Dockge - Stack management
- Homepage - Service dashboard
- And 50+ more services in the docs/service-docs/ folder
🏗️ Architecture
Core Infrastructure (Deploy on Main Server)
- DuckDNS - Dynamic DNS with wildcard SSL certificates
- Traefik - Reverse proxy with automatic HTTPS termination and multi-server routing
- Authelia - Single sign-on (SSO) authentication
Per-Server Infrastructure (Deploy on Each Server)
- Traefik - Local reverse proxy instance for container discovery
- Sablier - Lazy loading service for on-demand local container startup
Multi-Server Architecture
- Core Server: Only server with ports 80/443 forwarded from router
- Remote Servers: Connect to core via Docker TLS (port 2376)
- Unified Access: All services accessible through core server's domain
- Automatic Routing: Core Traefik discovers services on all servers
- Lazy Loading: Each server's Sablier manages local containers only
VPN Services
- Gluetun - VPN client for secure downloads
- qBittorrent - Torrent client routed through VPN
Service Categories
- Media - Plex, Jellyfin, Sonarr, Radarr
- VPN - qBittorrent (VPN-routed downloads)
- Productivity - Nextcloud, Gitea, BookStack, OnlyOffice
- Monitoring - Grafana, Prometheus, Uptime Kuma
- Home Automation - Home Assistant, Node-RED, Zigbee2MQTT
- Utilities - Backrest (backups), FreshRSS, Code Server
Key Features
- File-based configuration - AI-manageable YAML files
- Multi-server support - Scale across multiple machines with unified access
- Automated SSL - Wildcard certificates via Let's Encrypt
- Automatic routing - Traefik discovers services across all servers
- VPN routing - Secure download clients through Gluetun
- Resource limits - Prevent resource exhaustion
- SSO protection - Authelia integration with bypass options
- Lazy loading - Per-server Sablier enables on-demand container startup
- Automated backups - Restic + Backrest for comprehensive data protection
🤖 AI Management
This homelab is designed to be managed by AI agents through VS Code with GitHub Copilot. The system uses:
- Declarative configuration - Services defined in Docker Compose files
- Label-based routing - Traefik discovers services automatically
- Standardized patterns - Consistent environment variables and volumes
- Comprehensive documentation - AI instructions in
.github/copilot-instructions.md
📋 Requirements
- OS: Debian 11+, Ubuntu 20.04+
- RAM: 4GB minimum, 8GB+ recommended
- Storage: 50GB+ available space
- Network: Stable internet connection
- Hardware: x86_64 architecture (ARM support limited)
🔧 Manual Setup
If automated scripts fail, see:
- Manual Setup Guide - Step-by-step manual installation
- Troubleshooting - Common issues and solutions
🤝 Contributing
This project welcomes contributions! See individual service docs for configuration examples and deployment patterns.
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
Individual services may have their own licenses - please check the respective project repositories.
Built with ❤️ for the homelab community