EZ-Homelab/docs/getting-started.md

# Getting Started Guide

Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and 60+ services.

## Getting Started Checklist

- [ ] Configure `.env` file with your domain and tokens
- [ ] Run setup script (generates Authelia secrets and admin user)
- [ ] Log out and back in for Docker group permissions
- [ ] Run deployment script (deploys all core services)
- [ ] Access Dockge web UI
- [ ] Set up 2FA with Authelia
- [ ] Deploy additional stacks as needed via Dockge
- [ ] Configure Homepage dashboard widgets

## Quick Setup (Recommended)

For most users, the automated setup script handles everything:

### 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
2. **Install git if needed**
   ```bash
      sudo apt update && sudo apt upgrade -y && sudo apt install git

3. **Clone the rep**:
   ```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
   
6. **Log out and back in** (or run `newgrp docker`)
   > Don't skip this step! Required for Docker group permissions.

7. **Deploy homelab**:
   ```bash
   ./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

## Manual Setup (Alternative)

If you prefer manual control or the automated script fails, see the [Manual Setup Guide](manual-setup.md) for step-by-step instructions on installing Docker, configuring services, and deploying the homelab manually.

## Post-Setup Next Steps

### Access Your Services
- **Dockge**: `https://dockge.yourdomain.duckdns.org`
- **Authelia**: `https://auth.yourdomain.duckdns.org`
- **Traefik**: `https://traefik.yourdomain.duckdns.org`

### Set Up 2FA with Authelia
1. Access `https://auth.yourdomain.duckdns.org`
2. Set up your admin user
3. Configure 2FA for security

### Deploy Additional Stacks
Use Dockge to deploy stacks like:
- `arr-apps.yml` - Media management (Radarr, Sonarr, Prowlarr, etc.)
- `media-servers.yml` - Plex and Jellyfin
- `downloaders.yml` - qBittorrent, Transmission, etc.
- `monitoring.yml` - Uptime Kuma and metrics
- `system-tools.yml` - Utility services
- `automation.yml` - Automated workflows

**Note:** The dashboards stack (Homepage and Homarr) is already deployed during initial setup.

### Set Up Homepage Widgets
1. Access Homepage dashboard
2. Get API keys from services
3. Configure widgets in `/opt/stacks/dashboards/homepage/config/`

## VS Code Integration

1. Install VS Code and GitHub Copilot
2. Open the AI-Homelab repository
3. Use AI assistance for:
   - Adding new services
   - Configuring Traefik routing
   - Managing Docker stacks

## Troubleshooting

### Script Issues
- **Permission denied**: Run with `sudo`
- **Docker not found**: Log out/in or run `newgrp docker`
- **Network conflicts**: Check existing networks with `docker network ls`

### Service Issues
- **Can't access services**: Check Traefik dashboard at `https://traefik.yourdomain.duckdns.org`
- **SSL certificate errors**: Wait 2-5 minutes for wildcard certificate to be obtained from Let's Encrypt
  - Check status: `python3 -c "import json; d=json.load(open('/opt/stacks/core/traefik/acme.json')); print(f'Certificates: {len(d[\"letsencrypt\"][\"Certificates\"])}')"`
  - View logs: `docker exec traefik tail -50 /var/log/traefik/traefik.log | grep certificate`
- **Authelia login fails**: Check user database configuration at `/opt/stacks/core/authelia/users_database.yml`
- **"Not secure" warnings**: Clear browser cache or wait for DNS propagation (up to 5 minutes)
- **Check logs**: Use Dozzle web interface at `https://dozzle.yourdomain.duckdns.org` or run `docker logs <container-name>`

### Common Fixes
```bash
# Restart Docker
sudo systemctl restart docker

# Check service logs
cd /opt/stacks/stack-name
docker compose logs -f

# Rebuild service
docker compose up -d --build service-name
```

## Next Steps

1. **Explore services** through Dockge
2. **Configure backups** with Backrest/Duplicati
3. **Set up monitoring** with Grafana/Prometheus
4. **Add external services** via Traefik proxying
5. **Use AI assistance** for custom configurations

Happy homelabbing! 🚀