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 unified setup script:

   ./scripts/ez-homelab.sh
   

   The script will guide you through:

   • System preparation (if needed)
   • Domain and credential configuration
   • Service stack selection
   • Authelia secrets generation
   • SSL certificate setup
   • Service deployment

   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 Unified Setup Script Does

The ez-homelab.sh script is a comprehensive guided setup and deployment tool:

System Preparation (when needed):

• ✅ 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

Interactive Configuration:

• ✅ Guides through domain setup (DuckDNS)
• ✅ Prompts for admin username, email, and password
• ✅ Generates three cryptographic secrets (JWT, session, encryption)
• ✅ Generates argon2id password hash using Docker (30-60s process)
• ✅ Allows service stack selection
• ✅ Validates Docker is available before operations

Infrastructure Setup & Deployment:

• ✅ Creates directory structure (/opt/stacks/)
• ✅ Sets up Docker networks (homelab, traefik, dockerproxy, media)
• ✅ Deploys selected service stacks
• ✅ Obtains wildcard SSL certificate (*.yourdomain.duckdns.org)
• ✅ Detects NVIDIA GPU and offers driver installation
• ✅ Opens Dockge when ready

Safety Features:

• Interactive guidance with clear prompts
• Timeout handling (60s for Docker operations)
• Comprehensive error messages with troubleshooting hints
• Safe to re-run (idempotent operations)
• Confirmation prompts for destructive actions

Release-Specific Notes

• Version: Based on v0.1.0—ensure you're using the latest scripts.
• Stacks: Core, Infrastructure, and Dashboards deploy automatically. Others are inactive by default.
• Dashboards: Homepage is preconfigured at homepage.yoursubdomain.duckdns.org.
• Known Limitations: Options 1 & 2 require additional testing; use Option 3 for production.