EZ-Homelab/docs/automated-setup.md

Automated Setup (Recommended)

For most users, the automated setup script handles everything from system preparation to deployment.

Prerequisites

• Fresh Debian/Ubuntu server (or existing system)
• Root/sudo access
• Internet connection
• Ports 80 and 443 forwarded from your router to your server (required for SSL certificates)
• VS Code with GitHub Copilot (for AI assistance)

Simple Setup

1. Connect to your server via SSH

   Tip: Use VS Code on your local machine to ssh in to your server for the easiest install!

2. Install git if needed

      sudo apt update && sudo apt upgrade -y && sudo apt install git
   

3. Clone the repository:

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

4. Configure environment:

   cp .env.example .env
   nano .env  # Edit with your domain and tokens
   

   Required variables in .env:

   • 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

   Note: The .env file stays in the repository folder (~/EZ-Homelab/.env). The deploy script copies it to stack directories automatically. Authelia secrets (JWT, session, encryption key) are auto-generated by the setup script - leave them with default values for now.

5. Run the setup script:

   sudo ./scripts/setup-homelab.sh
   

   The script will:

   • Update system packages
   • Install Docker Engine + Compose V2 (if needed)
   • Configure user groups (docker, sudo)
   • Set up firewall (UFW)
   • Enable SSH server
   • Generate Authelia secrets (JWT, session, encryption key)
   • Prompt for admin username, password, and email
   • Generate argon2id password hash (30-60 seconds)
   • Create /opt/stacks/ directory structure
   • Set up Docker networks (homelab, traefik, dockerproxy, media)
   • Detect NVIDIA GPU and offer driver installation

   Important: If NVIDIA drivers were installed, reboot your system now before continuing.

6. Deploy homelab:

   sudo ./scripts/deploy-homelab.sh
   

   The deploy script automatically:

   • Creates Docker networks
   • Configures Traefik with your email and domain
   • Obtains wildcard SSL certificate (*.yourdomain.duckdns.org) via DNS challenge
   • Deploys core stack (DuckDNS, Traefik, Authelia, Gluetun)
   • Deploys infrastructure stack (Dockge, Pi-hole, monitoring)
   • Deploys dashboards stack (Homepage, Homarr)
   • Opens Dockge in your browser

   Note: Certificate generation may take 2-5 minutes. All services will use the wildcard certificate automatically.

   Login credentials:

   • Username: admin (default username - or the custom username you specified during setup)
   • Password: The secure password you created when prompted by the setup script

That's it! Your homelab is ready. Access Dockge at https://dockge.yourdomain.duckdns.org

What the Setup Script Does

The setup-homelab.sh script is a comprehensive first-run configuration tool:

System Preparation:

• ✅ Pre-flight checks (internet connectivity, disk space 50GB+)
• ✅ Updates system packages
• ✅ Installs required packages (git, curl, etc.)
• ✅ Installs Docker Engine + Compose V2 (if not present)
• ✅ Configures user permissions (docker, sudo groups)
• ✅ Sets up firewall (UFW with SSH, HTTP, HTTPS)
• ✅ Enables SSH server

Authelia Configuration (Interactive):

• ✅ Generates three cryptographic secrets (JWT, session, encryption)
• ✅ Prompts for admin username (default: admin)
• ✅ Prompts for secure password with confirmation
• ✅ Prompts for admin email address
• ✅ Generates argon2id password hash using Docker (30-60s process)
• ✅ Validates Docker is available before password operations
• ✅ Saves credentials securely for deployment script

Infrastructure Setup:

• ✅ Creates directory structure (/opt/stacks/)
• ✅ Sets up Docker networks (homelab, traefik, dockerproxy, media)
• ✅ Detects NVIDIA GPU and offers driver installation

Safety Features:

• Skips completed steps (safe to re-run)
• Timeout handling (60s for Docker operations)
• Comprehensive error messages with troubleshooting hints
• Exit on critical failures with clear next steps