====== Automated Setup ======

The AI-Homelab uses two automated scripts for deployment. This is the recommended approach for most users.

===== Quick Setup Commands =====

```bash
# 1. Clone the repository
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab

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

# 3. Run setup script
sudo ./scripts/setup-homelab.sh

# 4. Run deployment script
sudo ./scripts/deploy-homelab.sh
```

That's it! Your homelab will be ready in 10-15 minutes.

===== Detailed Setup Process =====

==== Step 1: Clone Repository ====

```bash
# Clone to your home directory
cd ~
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
```

**What this provides:**
  * Complete homelab configuration
  * Docker compose files for all services
  * Automated deployment scripts
  * Configuration templates
  * Documentation and guides

==== Step 2: Configure Environment ====

```bash
# Copy example configuration
cp .env.example .env

# Edit with your settings
nano .env
```

**Required variables:**
```
DOMAIN=yourdomain.duckdns.org
DUCKDNS_TOKEN=your-duckdns-token
ACME_EMAIL=your-email@example.com
```

**Optional variables:**
```
SURFSHARK_USERNAME=your-vpn-username
SURFSHARK_PASSWORD=your-vpn-password
TZ=America/New_York
PUID=1000
PGID=1000
```

==== Step 3: Run Setup Script ====

```bash
# Execute with sudo privileges
sudo ./scripts/setup-homelab.sh
```

**What the setup script does:**

**System Preparation:**
  * Updates system packages
  * Installs required dependencies (git, curl, etc.)
  * Installs Docker Engine + Compose V2
  * Configures user permissions
  * Sets up UFW firewall
  * Enables SSH server

**Authelia Configuration:**
  * Generates cryptographic secrets (JWT, session, encryption keys)
  * Prompts for admin username (default: admin)
  * Prompts for secure password with confirmation
  * Generates argon2id password hash
  * Creates user database

**Infrastructure Setup:**
  * Creates `/opt/stacks/` directory structure
  * Sets up Docker networks (traefik-network, homelab-network, etc.)
  * Detects NVIDIA GPU and offers driver installation

**Security Features:**
  * Idempotent (safe to re-run)
  * Comprehensive error handling
  * Timeout protection for operations
  * Clear troubleshooting messages

==== Step 4: Run Deployment Script ====

```bash
# Deploy all services
sudo ./scripts/deploy-homelab.sh
```

**What the deployment script does:**

**Prerequisites Check:**
  * Validates environment configuration
  * Verifies Docker installation
  * Checks network connectivity

**Core Stack Deployment:**
  * Deploys DuckDNS, Traefik, Authelia, Gluetun
  * Obtains wildcard SSL certificate (*.yourdomain.duckdns.org)
  * Configures reverse proxy routing

**Infrastructure Deployment:**
  * Deploys Dockge, Pi-hole, monitoring tools
  * Sets up dashboards (Homepage, Homarr)
  * Configures service discovery

**Health Checks:**
  * Waits for services to become healthy
  * Validates SSL certificate generation
  * Opens Dockge in browser

===== Post-Setup Configuration =====

==== Access Your Services ====

After deployment, access services at:

| Service | URL | Status |
|---------|-----|--------|
| **Dockge** | `https://dockge.yourdomain.duckdns.org` | ✅ Primary management |
| **Homepage** | `https://home.yourdomain.duckdns.org` | ✅ Service dashboard |
| **Authelia** | `https://auth.yourdomain.duckdns.org` | ✅ SSO login |
| **Traefik** | `https://traefik.yourdomain.duckdns.org` | ✅ Proxy dashboard |

**Default Credentials:**
  * Username: `admin` (or your custom username)
  * Password: The secure password you created

==== Configure Two-Factor Authentication ====

1. Visit `https://auth.yourdomain.duckdns.org`
2. Log in with your admin credentials
3. Go to Settings → One-Time Password
4. Scan QR code with authenticator app
5. Enter verification code to enable 2FA

==== Customize Homepage Dashboard ====

1. Visit `https://home.yourdomain.duckdns.org`
2. Click the settings icon (gear)
3. Configure services and widgets
4. Add API keys for enhanced widgets

===== Troubleshooting Setup =====

==== Common Issues ====

**"Permission denied" when running scripts:**
```bash
# Ensure you're using sudo
sudo ./scripts/setup-homelab.sh

# Check if scripts are executable
ls -la scripts/
chmod +x scripts/*.sh
```

**Docker installation fails:**
```bash
# Remove conflicting packages
sudo apt remove docker docker-engine docker.io containerd runc

# Re-run setup script
sudo ./scripts/setup-homelab.sh
```

**SSL certificate generation fails:**
  * Check DuckDNS token is correct in `.env`
  * Verify ports 80/443 are forwarded
  * Wait 2-5 minutes for DNS propagation
  * Check Traefik logs: `docker logs traefik`

**Services not accessible:**
  * Verify domain resolves: `nslookup yourdomain.duckdns.org`
  * Check firewall: `sudo ufw status`
  * View service logs: `docker compose -f /opt/stacks/core/docker-compose.yml logs`

==== NVIDIA GPU Setup ====

If you have an NVIDIA GPU and want hardware acceleration:

```bash
# During setup script, answer 'y' when prompted
# Or install manually after setup:

# Add NVIDIA package repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# Install NVIDIA Docker
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

# Test GPU access
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
```

==== Manual Setup Alternative ====

If automated scripts fail, see [[getting_started:manual|Manual Setup Guide]] for step-by-step instructions.

===== Next Steps =====

1. **Explore Services**: Use Dockge to deploy additional services
2. **Configure Backups**: Set up Backrest for automated backups
3. **Add Monitoring**: Deploy Grafana/Prometheus for observability
4. **Customize**: Modify services to fit your needs
5. **Contribute**: Help improve the project

**Ready to deploy?** Run the setup script and enjoy your new homelab!

**Need help?** Check [[troubleshooting:deployment|Deployment Troubleshooting]] or ask in [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]].