43f78b384f
- Updated all documentation references from AI-Homelab to EZ-Homelab - Changed repository URLs and directory paths - Updated wiki content and navigation - Maintained AI assistance functionality while emphasizing ease of use - Updated copilot instructions and agent guidelines
112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
# 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**
|
|
```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 (`~/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:**
|
|
```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 |