====== Prerequisites ======

Before deploying your AI-Homelab, ensure your system meets these requirements.

===== System Requirements =====

**Minimum Hardware:**
  * **CPU**: 2-core processor (4+ cores recommended)
  * **RAM**: 4GB minimum (8GB+ recommended)
  * **Storage**: 50GB free space (SSD preferred)
  * **Network**: Stable internet connection

**Recommended Hardware:**
  * **CPU**: 4+ core processor with virtualization support
  * **RAM**: 16GB+ for full stack deployment
  * **Storage**: 500GB+ SSD for media and backups
  * **GPU**: NVIDIA GPU (optional, for hardware transcoding)

===== Operating System =====

**Supported Systems:**
  * **Ubuntu 20.04+** (recommended)
  * **Debian 11+**
  * **Ubuntu Server**
  * **Raspberry Pi OS** (64-bit, for lightweight deployments)

**Fresh Installation Recommended:**
  * Start with a clean OS install
  * Avoid pre-installed Docker versions
  * Use LTS (Long Term Support) releases

===== Network Requirements =====

**Domain & DNS:**
  * **DuckDNS account**: [[https://duckdns.org|Create free account]]
  * **Domain**: Choose your subdomain (e.g., `yourname.duckdns.org`)
  * **Token**: Get your DuckDNS token from account settings

**Port Forwarding:**
  * **Port 80**: Required for Let's Encrypt HTTP challenge
  * **Port 443**: Required for HTTPS traffic
  * **Router**: Configure port forwarding to your server

**Network Access:**
  * **Outbound**: Full internet access for updates and services
  * **Inbound**: Ports 80/443 forwarded from router
  * **Local**: Access to router admin panel (for port forwarding)

===== Software Prerequisites =====

**Required Software:**
  * **Git**: Version control system
  * **curl/wget**: Download utilities
  * **SSH server**: Remote access (usually pre-installed)

**Optional but Recommended:**
  * **VS Code**: With GitHub Copilot extension
  * **Docker Desktop**: For local testing (Windows/Mac)
  * **NVIDIA drivers**: If using GPU acceleration

===== Account Setup =====

**Required Accounts:**
  * **DuckDNS**: Free dynamic DNS service
    * Visit [[https://duckdns.org]]
    * Create account and subdomain
    * Copy your token for configuration

**Optional Accounts (for specific services):**
  * **Surfshark VPN**: For secure downloads
  * **GitHub**: For repository access and Copilot
  * **Cloud storage**: For offsite backups

===== Security Considerations =====

**Firewall Setup:**
  * UFW (Uncomplicated Firewall) will be configured automatically
  * Only necessary ports will be opened
  * SSH access restricted to key-based authentication

**SSL Certificates:**
  * Let's Encrypt provides free certificates
  * Wildcard certificate covers all subdomains
  * Automatic renewal every 90 days

**Access Control:**
  * Authelia provides SSO (Single Sign-On)
  * 2FA (Two-Factor Authentication) recommended
  * Granular access control per service

===== Pre-Installation Checklist =====

**Hardware Check:**
  * [ ] Server meets minimum requirements
  * [ ] Sufficient storage space available
  * [ ] Stable power supply
  * [ ] Backup power (UPS) recommended

**Network Check:**
  * [ ] Internet connection stable
  * [ ] Router supports port forwarding
  * [ ] Ports 80/443 available and forwarded
  * [ ] Local IP address known and static

**Account Setup:**
  * [ ] DuckDNS account created
  * [ ] Domain chosen and configured
  * [ ] DuckDNS token obtained
  * [ ] Optional: VPN credentials prepared

**Software Preparation:**
  * [ ] SSH access to server established
  * [ ] VS Code installed (optional)
  * [ ] GitHub Copilot configured (optional)

===== Environment Variables =====

Create a `.env` file with these variables:

```
# Domain Configuration
DOMAIN=yourdomain.duckdns.org
DUCKDNS_TOKEN=your-duckdns-token

# Optional: VPN Configuration
SURFSHARK_USERNAME=your-vpn-username
SURFSHARK_PASSWORD=your-vpn-password

# Authelia (auto-generated by setup script)
AUTHELIA_JWT_SECRET=64-char-random-string
AUTHELIA_SESSION_SECRET=64-char-random-string
AUTHELIA_STORAGE_ENCRYPTION_KEY=64-char-random-string

# User Configuration
PUID=1000
PGID=1000
TZ=America/New_York
```

**Note:** Authelia secrets are auto-generated by the setup script. Leave them with default values initially.

===== Testing Your Setup =====

**Network Connectivity:**
```bash
# Test internet connection
ping -c 4 8.8.8.8

# Test DNS resolution
nslookup duckdns.org

# Test port forwarding (from external network)
curl -I http://your-external-ip
```

**System Resources:**
```bash
# Check available space
df -h /

# Check memory
free -h

# Check CPU cores
nproc
```

**SSH Access:**
```bash
# Test SSH connection
ssh user@your-server-ip

# Test sudo access
sudo whoami
```

===== Troubleshooting Prerequisites =====

**"Permission denied" errors:**
  * Ensure you have sudo access
  * Check if user is in sudo group
  * Try running commands with `sudo`

**Network connectivity issues:**
  * Verify internet connection
  * Check firewall settings
  * Test DNS resolution

**Port forwarding problems:**
  * Access router admin panel
  * Verify ports 80/443 are forwarded
  * Check if ISP blocks these ports

**DuckDNS issues:**
  * Verify token is correct
  * Check domain is available
  * Test DNS updates manually

Ready to proceed? Continue to [[getting_started:setup|Automated Setup]].

**Need Help?** Check the [[troubleshooting:start|Troubleshooting Guide]] or visit [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]].