# 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**
- **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**
   ```bash
      sudo apt update && sudo apt upgrade -y && sudo apt install git
3. **Clone the repository**:
   ```bash
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
4. **Configure environment**:
   ```bash
   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](https://www.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 (`~/AI-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:**
   ```bash
   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**:
   ```bash
   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