# 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](docs/getting-started.md): Step-by-step setup
- [Services Overview](docs/services-overview.md): All included services
- [Docker Guidelines](docs/docker-guidelines.md): Compose, network, and security patterns
- [Quick Reference](docs/quick-reference.md): Commands and troubleshooting
- [Proxying External Hosts](docs/proxying-external-hosts.md): Traefik file provider and SSO
- [Copilot Instructions](.github/copilot-instructions.md): 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:**
   ```bash
   cd ~
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
   ```

2. **Create and configure environment file:**
   ```bash
   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](https://www.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](docs/getting-started.md) 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
   ```bash
   cd ~
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
   ```

   ### 2. Configure environment
   ```bash
   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
   ```bash
   sudo ./scripts/setup-homelab.sh
   ```
   > Handles system prep, Docker install, secrets, and directory structure.

   ### 4. Run deployment script
   ```bash
   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`