AI-Homelab

AI-Homelab: Modern, AI-Managed Homelab Infrastructure

AI-Homelab is a production-ready, Docker Compose-based homelab stack managed with Dockge and supercharged by GitHub Copilot in VS Code. It features 60+ pre-configured services, automated SSL, SSO, VPN routing, and a file-based, AI-friendly architecture.

Key Features

• AI-Driven Management: Use GitHub Copilot to create, modify, and manage all services and infrastructure. Just describe what you want—the AI handles the rest.
• Dockge Structure: All stacks live in /opt/stacks/ for easy, visual management via Dockge web UI.
• Automated Setup: Two-script install (setup + deploy) with robust error handling and auto-generated secrets.
• Comprehensive Service Catalog: 60+ production-ready services across infrastructure, media, automation, productivity, and monitoring.
• Traefik Reverse Proxy: Automatic HTTPS with Let's Encrypt wildcard certs (DNS challenge via DuckDNS).
• Authelia SSO: Single Sign-On for all admin interfaces, with secure defaults and 2FA support.
• Gluetun VPN: Secure download stack with Surfshark WireGuard/OpenVPN integration.
• Homepage Dashboard: AI-configurable dashboard with dynamic service discovery and widgets.
• Proxy External Hosts: Easily route non-Docker services (e.g., Raspberry Pi, NAS) through Traefik.
• Stack-Aware Changes: AI considers the entire infrastructure for every change.
• File-Based Configuration: Everything managed via YAML—no web UI lock-in.

Documentation

• Getting Started: Step-by-step setup
• Services Overview: All included services
• Docker Guidelines: Compose, network, and security patterns
• Quick Reference: Commands and troubleshooting
• Proxying External Hosts: Traefik file provider and SSO
• Copilot Instructions: AI agent guidelines

---

Quick Start

Prerequisites

• Docker Engine 24.0+ installed
• Docker Compose V2
• Git
• VS Code with GitHub Copilot extension (for AI assistance)
• A domain from DuckDNS (free)
• Surfshark VPN account (optional, for VPN features)
• Sufficient disk space: 120GB+ system drive (NVMe or SSD highly recommended), 2TB+ for media & additional disks for services like Nextcloud that require lots of space

Quick Setup (Dockge Structure)

1. Clone the repository into your home folder:

   cd ~
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
   

2. Create and configure environment file:

   cp .env.example .env
   nano .env  # Edit with your domain, API keys, and passwords
   

   Alternatively you can ssh in from VS Code using the Remote-SSH plugin and edit in a nice editor

   IMPORTANT: Keep your .env file in the repository folder (~/AI-Homelab/.env). The deploy script will automatically copy it where needed.

   Required variables:

   • DOMAIN - Your DuckDNS domain (e.g., yourdomain.duckdns.org)
   • DUCKDNS_TOKEN - Your DuckDNS token from duckdns.org
   • ACME_EMAIL - Your email for Let's Encrypt certificates
   • SURFSHARK_USERNAME and SURFSHARK_PASSWORD - If using VPN features

   Note: Authelia secrets (AUTHELIA_JWT_SECRET, AUTHELIA_SESSION_SECRET, AUTHELIA_STORAGE_ENCRYPTION_KEY) are automatically generated by the setup script, leave default values for now.

   See Getting Started for detailed instructions

3. Run first-run setup script:

   This automated script handles system preparation and Authelia configuration. Safe to run on partially configured systems - it skips completed steps.

   Prerequisites

   • Docker Engine 24.0+
   • Docker Compose V2
   • Git
   • VS Code with GitHub Copilot extension
   • DuckDNS domain (free)
   • Surfshark VPN (optional, for VPN features)
   • 120GB+ system drive (SSD/NVMe recommended), 2TB+ for media

   1. Clone the repository

   cd ~
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
   

   2. Configure environment

   cp .env.example .env
   nano .env  # Set your domain, tokens, and passwords
   

   Keep .env in ~/AI-Homelab/. The deploy script copies it as needed.

   3. Run setup script

   sudo ./scripts/setup-homelab.sh
   

   Handles system prep, Docker install, secrets, and directory structure.

   4. Run deployment script

   sudo ./scripts/deploy-homelab.sh
   

   Deploys core, infrastructure, and dashboard stacks. Prepares all others for Dockge.

   5. Deploy more stacks via Dockge

   Visit https://dockge.yourdomain.duckdns.org and start any stack you want.

   6. Use VS Code + Copilot for management

   Install GitHub Copilot in VS Code. Use chat to manage, modify, and extend your homelab—just describe what you want!

   ---

   AI Capabilities & Examples

   You can ask the AI to:

   • Add, remove, or modify any service or stack
   • Refactor the stack structure (e.g., switch to Portainer)
   • Configure Traefik routing and Authelia SSO
   • Proxy external hosts (e.g., Raspberry Pi)
   • Create Homepage widgets and dashboards
   • Route services through VPN
   • Reorganize or customize anything

   Just describe your goal. The AI will handle the details, following .github/copilot-instructions.md for best practices.

   ---

   License & Acknowledgments

   This project is provided as-is for personal homelab use.

   Thanks to:

   • Docker & Compose communities
   • LinuxServer.io for container images
   • GitHub Copilot for AI capabilities
   • All open-source projects referenced

   ---

   Support

   • Use GitHub Copilot in VS Code for real-time help
   • Consult the comprehensive documentation in /docs