f141848a10
- Complete modular bash-based setup system replacing Python TUI - Phase 1-4 implementation: Core Infrastructure, Configuration Management, Deployment Engine, Service Orchestration & Management - 9 production-ready scripts: preflight.sh, setup.sh, pre-deployment-wizard.sh, localize.sh, generalize.sh, validate.sh, deploy.sh, service.sh, monitor.sh, backup.sh, update.sh - Shared libraries: common.sh (utilities), ui.sh (text interface) - Template-based configuration system with environment variable substitution - Comprehensive documentation: PRD, standards, and quick reference guides - Automated backup, monitoring, and update management capabilities - Cross-platform compatibility with robust error handling and logging
AI-Homelab Documentation
Welcome to the AI-Homelab documentation! This is your comprehensive guide to deploying and managing a production-ready homelab infrastructure with 50+ pre-configured services.
Mission Statement
Provide a fast, convenient, and free way to deploy homelab servers with popular features
- DuckDNS subdomains with LetsEncrypt SSL wildcard certificates
- Security First - Secure Single Sign On with Authelia
- Traefik - Proxy Host for an entire homelab
- Sablier - Lazy Loading of services
- TLS Certificates for docker proxy
Deployment Scenarios
-
Single server
Select Option 1
- Use Dockge to start the desired stacks
- Use Homepage to explore your services
-
Core Server + Remote Server
Core Server
- A small low power device, like a Raspberry Pi 4 4GB.
- Deploy core stack. (Authelia, DuckDNS, Traefik, Sablier, Homepage)
- Functions as a gateway between the internet and your servers.
- Configure a remote host file for each Remote Server.
- Configure sablier.yml for services to lazyload.
- Generate TLS certificate, all servers use the same TLS certificate for dockerproxy
Remote Server(s)
- Your old office or gaming PC, SBCs, second hand PCs, etc
- Select Option 3 to install Infrastructure only
- Ensure the TLS certificate was copied correctly and docker daemon configured
- Use Dockge to start the desired stacks
- Use Homepage to explore your services
📚 Documentation Structure
🚀 Getting Started
- Quick Start Guide - Step-by-step setup for new users
- Prerequisites & Requirements - What you need before starting
- First Deployment - Automated setup process
🏗️ Architecture & Design
- System Architecture - High-level overview of components
- Network Architecture - How services communicate
- Security Model - Authentication, SSL, and access control
- Storage Strategy - Data persistence and organization
💾 Backup & Recovery
- Backup Strategy - Comprehensive Restic + Backrest guide (default strategy)
- Backrest Service - Web UI for backup management
📦 Services & Stacks
Core Infrastructure (Deploy First)
Essential services that everything else depends on:
- DuckDNS - Dynamic DNS updates
- Traefik - Reverse proxy & SSL termination
- Authelia - Single Sign-On authentication
- Gluetun - VPN client for secure downloads
- Sablier - Lazy loading service for on-demand containers
Management & Monitoring
- Dockge - Primary stack management UI
- Homepage - Service dashboard (AI-configurable)
- Homarr - Alternative modern dashboard
- Dozzle - Real-time log viewer
- Glances - System monitoring
- Pi-hole - DNS & ad blocking
Media Services
- Jellyfin - Open-source media streaming
- Plex - Popular media server (alternative)
- qBittorrent - Torrent client (VPN-routed)
- Calibre-Web - Ebook reader & server
Media Management (Arr Stack)
- Sonarr - TV show automation
- Radarr - Movie automation
- Prowlarr - Indexer management
- Readarr - Ebook/audiobook automation
- Lidarr - Music library management
- Bazarr - Subtitle automation
- Jellyseerr - Media request interface
Home Automation
- Home Assistant - Smart home platform
- Node-RED - Flow-based programming
- Zigbee2MQTT - Zigbee device integration
- ESPHome - ESP device firmware
- TasmoAdmin - Tasmota device management
- MotionEye - Video surveillance
Productivity & Collaboration
- Nextcloud - Self-hosted cloud storage
- Gitea - Git service (GitHub alternative)
- BookStack - Documentation/wiki platform
- WordPress - Blog/CMS platform
- MediaWiki - Wiki platform
- DokuWiki - Simple wiki
- Excalidraw - Collaborative drawing
Development Tools
- Code Server - VS Code in the browser
- GitLab - Complete DevOps platform
- Jupyter - Interactive computing
- pgAdmin - PostgreSQL administration
Monitoring & Observability
- Grafana - Metrics visualization
- Prometheus - Metrics collection
- Uptime Kuma - Uptime monitoring
- Loki - Log aggregation
- Promtail - Log shipping
- Node Exporter - System metrics
- cAdvisor - Container metrics
Utilities & Tools
- Backrest - Backup management (Restic-based, default)
- Duplicati - Alternative backup solution
- FreshRSS - RSS feed reader
- Wallabag - Read-it-later service
- Watchtower - Automatic updates
- Vaultwarden - Password manager
Alternative Services
Services that provide alternatives to the defaults:
🛠️ Development & Operations
Docker & Container Management
- Docker Guidelines - Complete service management guide
- Service Creation - How to add new services
- Service Modification - Updating existing services
- Resource Limits - CPU/memory management
- Troubleshooting - Common issues & fixes
External Service Integration
- Proxying External Hosts - Route non-Docker services through Traefik
- External Host Examples - Raspberry Pi, NAS, etc.
AI & Automation
- Copilot Instructions - AI agent guidelines for this codebase
- AI Management Capabilities - What the AI can help with
📋 Quick References
Commands & Operations
- Quick Reference - Essential commands and workflows
- Stack Management - Start/stop/restart services
- Deployment Scripts - Setup and deployment automation
Troubleshooting
- Common Issues - SSL, networking, permissions
- Service Won't Start - Debugging steps
- Traefik Routing - Route configuration issues
- VPN Problems - Gluetun troubleshooting
📖 Advanced Topics
SSL & Certificates
- Wildcard SSL Setup - How SSL certificates work
- Certificate Troubleshooting - SSL issues and fixes
- DNS Challenge Process - How domain validation works
Security & Access Control
- Authelia Configuration - SSO setup and customization
- Bypass Rules - When to skip authentication
- 2FA Setup - Two-factor authentication
Backup & Recovery
- Backup Strategies - Data protection approaches
- Service Backups - Database backup solutions
- Configuration Backup - Config file preservation
🔧 Development & Contributing
Repository Structure
- File Organization - How files are organized
- Service Documentation - Individual service guides
- Configuration Templates - Reusable configurations
- Scripts - Automation and deployment tools
Development Workflow
- Adding Services - New service integration
- Testing Changes - Validation procedures
- Resource Limits - Performance management
📚 Additional Resources
- GitHub Repository - Source code and issues
- Docker Hub - Container images
- Traefik Documentation - Official reverse proxy docs
- Authelia Documentation - SSO documentation
- DuckDNS - Dynamic DNS service
🎯 Quick Navigation
New to AI-Homelab? → Getting Started
Need to add a service? → Service Creation Guide
Having issues? → Troubleshooting
Want to contribute? → Development Workflow
🌐 Community Resources
For community-contributed examples, user experiences, and additional guides, visit the EZ-Homelab Wiki.
This documentation is maintained by AI and community contributors. Last updated: January 26, 2026