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 40+ services.

## 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

4. **Run the setup script**:
   ```bash
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
   sudo ./scripts/setup-homelab.sh
   ```
5. **Log out and back in** (or run `newgrp docker`)
6. **Generate Authelia/Authentik Secrets
   ```bash
   # TODO: provide instructions for generating required secrets
   AUTHELIA_JWT_SECRET=your-jwt-secret-here-64-chars
   AUTHELIA_SESSION_SECRET=your-session-secret-here-64-chars
   AUTHELIA_STORAGE_ENCRYPTION_KEY=your-encryption-key-here-64-chars
   AUTHENTIK_SECRET_KEY=your-authentik-secret-key-here-100-chars

8. **Configure environment**:
   ```bash
   cp .env.example .env
   nano .env  # Edit with your settings
   ```
9. **Deploy core services**:
   ```bash
   ./scripts/deploy-homelab.sh
   ```

**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 automatically:
- ✅ Updates system packages
- ✅ Installs Docker (if not present)
- ✅ Configures user permissions
- ✅ Sets up firewall (UFW)
- ✅ Enables SSH server
- ✅ Installs NVIDIA drivers (if GPU detected)
- ✅ Creates directory structure
- ✅ Sets up Docker networks

It safely skips steps that are already completed, so it's safe to run on partially configured systems.

## Manual Setup (Alternative)

If you prefer manual control or the script fails, follow these steps:

### Step 1: System Preparation
```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y curl wget git ufw openssh-server

# Enable firewall
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
```

### Step 2: Install Docker
```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
sudo usermod -aG sudo $USER

# Log out and back in, or run: newgrp docker
```

### Step 3: Clone Repository
```bash
cd ~
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
```

### Step 4: Configure Environment
```bash
cp .env.example .env
nano .env  # Edit all required variables
```

### Step 5: Create Infrastructure
```bash
# Create directories
sudo mkdir -p /opt/stacks /mnt/{media,database,downloads,backups}
sudo chown -R $USER:$USER /opt/stacks /mnt

# Create networks
docker network create traefik-network
docker network create homelab-network
docker network create media-network
```

### Step 6: Deploy Services
```bash
# Deploy core infrastructure
sudo mkdir -p /opt/stacks/core
cp docker-compose/core.yml /opt/stacks/core/
cp -r config-templates/traefik /opt/stacks/core/
cp -r config-templates/authelia /opt/stacks/core/
cp .env /opt/stacks/core/
cd /opt/stacks/core
docker compose up -d

# Deploy infrastructure stack
sudo mkdir -p /opt/stacks/infrastructure
cp ../docker-compose/infrastructure.yml /opt/stacks/infrastructure/
cp ../.env /opt/stacks/infrastructure/
cd /opt/stacks/infrastructure
docker compose up -d
```

## Post-Setup Configuration

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

### Configure 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:
- `dashboards.yml` - Homepage and Homarr
- `media.yml` - Plex, Jellyfin, Sonarr, Radarr
- `productivity.yml` - Nextcloud, Gitea, wikis

### 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
- **SSL certificate errors**: Wait for Let's Encrypt
- **Authelia login fails**: Check user database configuration

### 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
```

## Getting Started Checklist

- [ ] Run setup script or manual setup
- [ ] Configure `.env` file
- [ ] Deploy core infrastructure
- [ ] Access Dockge web UI
- [ ] Set up Authelia authentication
- [ ] Deploy additional stacks as needed
- [ ] Configure Homepage dashboard
- [ ] Install VS Code with Copilot

## 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! 🚀