EZ-Homelab/docs/quick-reference.md

# Quick Reference Guide

## Stack Overview

Your homelab uses separate stacks for organization:

**Deployed by default (12 containers):**
- **`core.yml`** - Essential infrastructure (Traefik, Authelia, DuckDNS, Gluetun) - 4 services
- **`infrastructure.yml`** - Management tools (Dockge, Pi-hole, Dozzle, Glances, Docker Proxy) - 6 services  
  _Note: Watchtower temporarily disabled due to Docker API compatibility_
- **`dashboards.yml`** - Dashboard services (Homepage, Homarr) - 2 services

**Available in Dockge (deploy as needed):**
- **`media.yml`** - Media services (Plex, Jellyfin, Sonarr, Radarr, Prowlarr, qBittorrent)
- **`media-extended.yml`** - Additional media tools (Readarr, Lidarr, Mylar, Calibre)
- **`homeassistant.yml`** - Home automation (Home Assistant, Node-RED, Zigbee2MQTT, ESPHome)
- **`productivity.yml`** - Productivity apps (Nextcloud, Gitea, Bookstack, Outline, Excalidraw)
- **`monitoring.yml`** - Monitoring stack (Grafana, Prometheus, Uptime Kuma, Netdata)
- **`utilities.yml`** - Utility services (Duplicati, Code Server, FreshRSS, Wallabag)
- **`alternatives.yml`** - Alternative tools (Portainer, Authentik)

> All stacks can be modified by the AI to suit your preferences.

## Deployment Scripts

### setup-homelab.sh

First-run system preparation and Authelia configuration:

```bash
sudo ./scripts/setup-homelab.sh
```

**What it does:**
- Pre-flight checks (internet, disk space 50GB+)
- Installs Docker Engine + Compose V2
- Configures user groups and firewall
- Generates Authelia secrets automatically
- Creates admin user with secure password hash
- Sets up Docker networks and directory structure
- Detects NVIDIA GPU and offers driver installation

**Safe to re-run** - skips completed steps

### deploy-homelab.sh

Deploys all core services and prepares additional stacks:

```bash
./scripts/deploy-homelab.sh
```

**What it does:**
- Validates Docker installation
- Deploys core stack (4 containers)
- Deploys infrastructure stack (6 containers)
- Deploys dashboards with configured URLs (2 containers)
- Copies 7 additional stacks to Dockge (not started)
- Optional: Pre-pull images for additional stacks
- Opens Dockge in browser

### reset-test-environment.sh

**Testing/development only** - safely removes all deployed services:

```bash
sudo ./scripts/reset-test-environment.sh
```

**What it does:**
- Gracefully stops all Docker Compose stacks
- Removes Docker volumes (after 3s wait)
- Cleans stack directories and temp files
- Removes Docker networks
- Prunes unused Docker resources

**Warning:** This is destructive! Only use for testing or complete reset.

## Common Commands

### Service Management

```bash
# Start all services in a stack (from stack directory)
cd /opt/stacks/stack-name/
docker compose up -d

# Start all services (from anywhere, using full path)
docker compose -f /opt/stacks/stack-name/docker-compose.yml up -d

# Start specific service (from stack directory)
cd /opt/stacks/stack-name/
docker compose up -d service-name

# Start specific service (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml up -d service-name

# Stop all services (from stack directory)
cd /opt/stacks/stack-name/
docker compose down

# Stop all services (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml down

# Stop specific service (from stack directory)
cd /opt/stacks/stack-name/
docker compose stop service-name

# Stop specific service (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml stop service-name

# Restart service (from stack directory)
cd /opt/stacks/stack-name/
docker compose restart service-name

# Restart service (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml restart service-name

# Remove service and volumes (from stack directory)
cd /opt/stacks/stack-name/
docker compose down -v

# Remove service and volumes (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml down -v
```

### Monitoring

> Tip: install the Dozzle service for viewing live logs

```bash
# View logs for entire stack
cd /opt/stacks/stack-name/
docker compose logs -f

# View logs for specific service
cd /opt/stacks/stack-name/
docker compose logs -f service-name

# View last 100 lines
cd /opt/stacks/stack-name/
docker compose logs --tail=100 service-name

# Check service status
docker compose -f /opt/stacks/stack-name/docker-compose.yml ps

# View resource usage
docker stats

# Inspect service
docker inspect container-name
```

### Updates

> Tip: Install the Watchtower service for automatic updates

```bash
# Pull latest images for stack
cd /opt/stacks/stack-name/
docker compose pull

# Pull and update specific service
cd /opt/stacks/stack-name/
docker compose pull service-name
docker compose up -d service-name
```

### Network Management

```bash
# List all networks
docker network ls

# Inspect network
docker network inspect traefik-network

# Create network (if needed)
docker network create network-name

# Remove unused networks
docker network prune
```

### Volume Management

```bash
# List volumes
docker volume ls

# Inspect volume
docker volume inspect volume-name

# Remove unused volumes
docker volume prune

# Backup volume
docker run --rm \
  -v volume-name:/data \
  -v $(pwd)/backups:/backup \
  busybox tar czf /backup/volume-backup.tar.gz /data

# Restore volume
docker run --rm \
  -v volume-name:/data \
  -v $(pwd)/backups:/backup \
  busybox tar xzf /backup/volume-backup.tar.gz -C /
```

### System Maintenance

```bash
# View disk usage
docker system df

# Clean up unused resources
docker system prune

# Clean up everything (use carefully!)
docker system prune -a --volumes

# Remove unused images
docker image prune -a
```

## Port Reference

### Core Infrastructure (core.yml)
- **80/443**: Traefik (reverse proxy)
- **8080**: Traefik dashboard

### Infrastructure Services (infrastructure.yml)
- **5001**: Dockge (stack manager)
- **9000/9443**: Portainer (Docker UI)
- **53**: Pi-hole (DNS)
- **8082**: Pi-hole (web UI)
- **9999**: Watchtower (auto-updates)
- **8000**: Dozzle (log viewer)
- **61208**: Glances (system monitor)

### Dashboard Services (dashboards.yml)
- **3000**: Homepage dashboard
- **7575**: Homarr dashboard

### Media Services (media.yml)
- **32400**: Plex
- **8096**: Jellyfin
- **8989**: Sonarr
- **7878**: Radarr
- **9696**: Prowlarr
- **8081**: qBittorrent

### Extended Media (media-extended.yml)
- **8787**: Readarr
- **8686**: Lidarr
- **5299**: Lazy Librarian
- **8090**: Mylar3
- **8083**: Calibre-Web
- **5055**: Jellyseerr
- **9697**: FlareSolverr
- **7889**: Tdarr Server
- **8265**: Unmanic

### Home Automation (homeassistant.yml)
- **8123**: Home Assistant
- **6052**: ESPHome
- **8843**: TasmoAdmin
- **1880**: Node-RED
- **1883/9001**: Mosquitto (MQTT)
- **8124**: Zigbee2MQTT
- **8081**: MotionEye

### Productivity (productivity.yml)
- **8080**: Nextcloud
- **9929**: Mealie
- **8084**: WordPress
- **3000**: Gitea
- **8085**: DokuWiki
- **8086**: BookStack
- **8087**: MediaWiki
- **3030**: Form.io

### Monitoring (monitoring.yml)
- **9090**: Prometheus
- **3000**: Grafana
- **3100**: Loki
- **9080**: Promtail
- **9100**: Node Exporter
- **8080**: cAdvisor
- **3001**: Uptime Kuma

### Utilities (utilities.yml)
- **7979**: Backrest (backups)
- **8200**: Duplicati (backups)
- **8443**: Code Server
- **5000**: Form.io
- **3001**: Uptime Kuma

### Development (development.yml)
- **8929**: GitLab
- **5432**: PostgreSQL
- **6379**: Redis
- **5050**: pgAdmin
- **8888**: Jupyter Lab

## Environment Variables Quick Reference

```bash
# User IDs (get with: id -u and id -g)
PUID=1000              # Your user ID
PGID=1000              # Your group ID

# General
TZ=America/New_York    # Your timezone
DOMAIN=yourdomain.duckdns.org  # Your domain

# DuckDNS
DUCKDNS_TOKEN=your-token
DUCKDNS_SUBDOMAINS=yourdomain

# Authelia
AUTHELIA_JWT_SECRET=64-char-secret
AUTHELIA_SESSION_SECRET=64-char-secret
AUTHELIA_STORAGE_ENCRYPTION_KEY=64-char-secret

# Database passwords
MYSQL_ROOT_PASSWORD=secure-password
POSTGRES_PASSWORD=secure-password

# API Keys (service-specific)
SONARR_API_KEY=your-api-key
RADARR_API_KEY=your-api-key
```

## Network Setup

```bash
# Create all required networks (setup script does this)
docker network create traefik-network
docker network create homelab-network
docker network create media-network
docker network create dockerproxy-network
```

## Service URLs

After deployment, access services at:

```
Core Infrastructure:
https://traefik.${DOMAIN}     - Traefik dashboard
https://auth.${DOMAIN}        - Authelia login

Infrastructure:
https://dockge.${DOMAIN}       - Stack manager (PRIMARY)
https://portainer.${DOMAIN}    - Docker UI (secondary)
http://${SERVER_IP}:8082       - Pi-hole admin
https://dozzle.${DOMAIN}       - Log viewer
https://glances.${DOMAIN}      - System monitor

Dashboards:
https://home.${DOMAIN}         - Homepage dashboard
https://homarr.${DOMAIN}       - Homarr dashboard

Media:
https://plex.${DOMAIN}         - Plex (no auth)
https://jellyfin.${DOMAIN}     - Jellyfin (no auth)
https://sonarr.${DOMAIN}       - TV automation
https://radarr.${DOMAIN}       - Movie automation
https://prowlarr.${DOMAIN}     - Indexer manager
https://qbit.${DOMAIN}         - Torrent client

Productivity:
https://nextcloud.${DOMAIN}    - File sync
https://git.${DOMAIN}          - Git service
https://docs.${DOMAIN}         - Documentation

Monitoring:
https://grafana.${DOMAIN}      - Metrics dashboard
https://prometheus.${DOMAIN}   - Metrics collection
https://status.${DOMAIN}       - Uptime monitoring
```

## Troubleshooting

### SSL Certificates

```bash
# Check wildcard certificate status
python3 -c "import json; d=json.load(open('/opt/stacks/core/traefik/acme.json')); print(f'Certificates: {len(d[\"letsencrypt\"][\"Certificates\"])}')"

# Verify certificate being served
echo | openssl s_client -connect auth.yourdomain.duckdns.org:443 -servername auth.yourdomain.duckdns.org 2>/dev/null | openssl x509 -noout -subject -issuer

# Check DNS TXT records (for DNS challenge)
dig +short TXT _acme-challenge.yourdomain.duckdns.org

# View Traefik certificate logs
docker exec traefik tail -50 /var/log/traefik/traefik.log | grep -E "acme|certificate"

# Reset certificates (if needed)
docker compose -f /opt/stacks/core/docker-compose.yml down
rm /opt/stacks/core/traefik/acme.json
touch /opt/stacks/core/traefik/acme.json
chmod 600 /opt/stacks/core/traefik/acme.json
sleep 60  # Wait for DNS to clear
docker compose -f /opt/stacks/core/docker-compose.yml up -d
```

**Important:** With DuckDNS, only Traefik should request certificates (wildcard cert covers all subdomains). Other services use `tls=true` without `certresolver`.

## Troubleshooting Quick Fixes

### Service won't start
```bash
# Check logs
docker compose -f /opt/stacks/stack-name/docker-compose.yml logs service-name

# Validate configuration
docker compose -f /opt/stacks/stack-name/docker-compose.yml config

# Check port conflicts
sudo netstat -tlnp | grep :PORT

# Restart Docker
sudo systemctl restart docker
```

### Permission errors
```bash
# Check your IDs match .env
id -u  # Should match PUID
id -g  # Should match PGID

# Fix ownership
sudo chown -R $USER:$USER /opt/stacks/stack-name/
```

### Network issues
```bash
# Check network exists
docker network inspect traefik-network

# Recreate network
docker network rm traefik-network
docker network create traefik-network
```

### Container keeps restarting
```bash
# Watch logs in real-time
docker compose -f /opt/stacks/stack-name/docker-compose.yml logs -f service-name

# Check resource usage
docker stats container-name

# Inspect container
docker inspect container-name | jq .State
```

### SSL certificate issues
```bash
# Check Traefik logs
docker logs traefik

# Check acme.json permissions
ls -la /opt/stacks/core/traefik/acme.json

# Force certificate renewal
# Remove acme.json and restart Traefik
```

## Testing GPU Support (NVIDIA)

```bash
# Test if nvidia-container-toolkit works
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

# Should show your GPU info if working
```

## Backup Commands

```bash
# Backup all config directories
tar czf backup-config-$(date +%Y%m%d).tar.gz /opt/stacks/

# Backup specific volume
docker run --rm \
  -v volume-name:/data \
  -v /mnt/backups:/backup \
  busybox tar czf /backup/volume-name-$(date +%Y%m%d).tar.gz /data

# Backup .env file securely
cp .env .env.backup
```

## Health Checks

```bash
# Check all container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# Check specific service health
docker inspect --format='{{json .State.Health}}' container-name | jq

# Test service connectivity
curl -k https://service.${DOMAIN}
```

## Resource Limits

Add to service definition if needed:

```yaml
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 4G
    reservations:
      cpus: '0.5'
      memory: 1G
```

## Common Patterns

### Add a new service to existing stack
1. Edit `/opt/stacks/stack-name/docker-compose.yml`
2. Add service definition following existing patterns
3. Use environment variables from `.env`
4. Connect to appropriate networks
5. Add Traefik labels for routing
6. Test: `docker compose config`
7. Deploy: `docker compose up -d`

### Create a new stack
1. Create directory: `mkdir /opt/stacks/new-stack`
2. Copy compose file: `cp docker-compose/template.yml /opt/stacks/new-stack/docker-compose.yml`
3. Copy env: `cp .env /opt/stacks/new-stack/`
4. Edit configuration
5. Deploy: `cd /opt/stacks/new-stack && docker compose up -d`

### Update service version
1. Edit compose file with new image tag
2. Pull new image: `docker compose pull service-name`
3. Recreate: `docker compose up -d service-name`
4. Check logs: `docker compose logs -f service-name`

### Remove a service
1. Stop service: `docker compose stop service-name`
2. Remove from compose file
3. Remove service: `docker compose rm service-name`
4. Optional: Remove volumes: `docker volume rm volume-name`

## AI Assistant Usage in VS Code

### Ask for help:
- "Add Jellyfin to my media stack"
- "Configure GPU for Plex"
- "Create monitoring dashboard setup"
- "Help me troubleshoot port conflicts"
- "Generate a compose file for Home Assistant"

### The AI will:
- Check existing services and avoid conflicts
- Follow naming conventions and patterns
- Configure Traefik labels automatically
- Apply Authelia middleware appropriately
- Suggest proper volume mounts
- Add services to Homepage dashboard

## Quick Deployment

### Minimal setup
```bash
# Clone and configure
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
sudo ./scripts/setup-homelab.sh
cp .env.example .env
nano .env

# Deploy core only
mkdir -p /opt/stacks/core
cp docker-compose/core.yml /opt/stacks/core/docker-compose.yml
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
```

### Full stack deployment
```bash
# After core is running, deploy all stacks
# Use Dockge UI at https://dockge.yourdomain.duckdns.org
# Or deploy manually:
docker compose -f docker-compose/infrastructure.yml up -d
docker compose -f docker-compose/dashboards.yml up -d
docker compose -f docker-compose/media.yml up -d
# etc.
```

## Maintenance Schedule

### Daily (automated)
- Watchtower checks for updates at 4 AM

### Weekly
- Review logs for each stack
- Check disk space: `docker system df`

### Monthly
- Update pinned versions in compose files
- Backup volumes and configs
- Review security updates

### Quarterly
- Full system audit
- Documentation review
- Performance optimization

## Emergency Commands

```bash
# Stop all containers
docker stop $(docker ps -q)

# Remove all containers
docker rm $(docker ps -aq)

# Remove all images
docker rmi $(docker images -q)

# Reset Docker (nuclear option)
sudo systemctl stop docker
sudo rm -rf /var/lib/docker
sudo systemctl start docker
```