Stub out stale documentation, rebuild as Linux-only

ADVANCED.md, INSTALLATION.md, and TROUBLESHOOTING.md were ~60-70% stale: references to deleted Path B scripts, macOS/WSL2 platform sections, old GitHub URLs, and v3.1-3.3 version history. Pruned to accurate Linux-only stubs to be rebuilt as the 1.0.0 codebase stabilises. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-10 21:17:16 -04:00
parent 148a0827e3
commit a7213441da
3 changed files with 130 additions and 1303 deletions
@@ -1,715 +1,64 @@
-# Advanced Configuration & Troubleshooting
+# Advanced Configuration
-This guide covers advanced HOPS configuration, troubleshooting, security features, and system administration.
+This guide covers advanced HOPS configuration and system administration.
-## 🔧 Advanced Configuration
+> **Note**: This document is being rebuilt alongside the 1.0.0 codebase.
 > Content will be expanded as features are stabilized.
-### Environment Variables
+## Environment Variables
-HOPS uses both encrypted secret management and traditional environment files for configuration.
+HOPS writes a `.env` file to `~/hops/` during installation. Key variables:
 #### Encrypted Secret Management (v3.1.0+)
 ```bash
-# Initialize secret management
+PUID=1000                    # User ID (run: id -u)
-./lib/secrets.sh init
+PGID=1000                    # Group ID (run: id -g)
 # Create encrypted environment
 ./lib/secrets.sh create
 # Update values
 ./lib/secrets.sh update DOMAIN example.com
 ./lib/secrets.sh update ACME_EMAIL admin@example.com
 # Retrieve values
 ./lib/secrets.sh get PUID
 ./lib/secrets.sh get DEFAULT_ADMIN_PASSWORD
 # List all keys
 ./lib/secrets.sh list
 # Backup encrypted secrets
 ./lib/secrets.sh backup /backup/location/
 ```
 #### Traditional Environment File (~/hops/.env)
 ```bash
 # User and Group Configuration
 PUID=1000                     # User ID
 PGID=1000                     # Group ID
 TZ=America/New_York          # Timezone
-# Directory Configuration
+DATA_ROOT=/mnt/media         # Media storage
-DATA_ROOT=/mnt/media         # Media storage (Linux)
+CONFIG_ROOT=/opt/appdata     # App configurations
 CONFIG_ROOT=/opt/appdata     # App configurations (Linux)
-# macOS paths (automatically set)
+DEFAULT_ADMIN_PASSWORD=...   # Auto-generated
-DATA_ROOT=/Users/username/hops/media
+DEFAULT_DB_PASSWORD=...      # Auto-generated
 CONFIG_ROOT=/Users/username/hops/config
 # Security (auto-generated and encrypted)
 DEFAULT_ADMIN_PASSWORD=...   # Generated secure password
 DEFAULT_DB_PASSWORD=...      # Database password
 JELLYFIN_PASSWORD=...        # Service-specific passwords
 # Optional: Custom Domain Configuration
 DOMAIN=yourdomain.com
 ACME_EMAIL=admin@yourdomain.com
 # Optional: Service Overrides
 JELLYFIN_PORT=8096
 SONARR_PORT=8989
 RADARR_PORT=7878
 ```
-### Service-Specific Configuration
+## Docker Compose Commands
 #### Reverse Proxy Setup
 **Traefik Configuration:**
 ```bash
 # Traefik automatically configured with labels
 # Custom configuration in ~/hops/config/traefik/
 # Example dynamic configuration
 mkdir -p ~/hops/config/traefik/dynamic
 cat > ~/hops/config/traefik/dynamic/middleware.yml << 'EOF'
 http:
  middlewares:
    default-headers:
      headers:
        frameDeny: true
        sslRedirect: true
        browserXssFilter: true
        contentTypeNosniff: true
        forceSTSHeader: true
        stsIncludeSubdomains: true
        stsPreload: true
        stsSeconds: 31536000
 EOF
 ```
 **Nginx Proxy Manager:**
 - Access admin interface on port 81
 - Default credentials: `admin@example.com` / `changeme`
 - Configure SSL certificates through web interface
 **Caddy Configuration:**
 ```bash
 # Create Caddy configuration directory
 mkdir -p ~/hops/config/caddy
 # Create custom Caddyfile
 cat > ~/hops/config/caddy/Caddyfile << 'EOF'
 # Global options
 {
    email your-email@domain.com
    # Optional: Use custom CA
    # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
 }
 # Main domain
 yourdomain.com {
    reverse_proxy jellyfin:8096
    # Custom headers
    header {
        # Security headers
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "strict-origin-when-cross-origin"
    }
 }
 # Subdomain routing
 sonarr.yourdomain.com {
    reverse_proxy sonarr:8989
 }
 radarr.yourdomain.com {
    reverse_proxy radarr:7878
 }
 # Internal services (authentication required)
 portainer.yourdomain.com {
    reverse_proxy portainer:9000
    # Optional: IP allowlist
    @internal {
        remote_ip 192.168.1.0/24 10.0.0.0/8
    }
    handle @internal {
        reverse_proxy portainer:9000
    }
    handle {
        respond "Access denied" 403
    }
 }
 EOF
 ```
 #### Authelia Integration
 ```bash
 # Authelia configuration
 mkdir -p ~/hops/config/authelia
 # Example configuration (simplified)
 cat > ~/hops/config/authelia/configuration.yml << 'EOF'
 theme: dark
 default_redirection_url: https://yourdomain.com
 server:
  host: 0.0.0.0
  port: 9091
 log:
  level: warn
 authentication_backend:
  file:
    path: /config/users_database.yml
    password:
      algorithm: argon2id
 access_control:
  default_policy: deny
  rules:
    - domain: jellyfin.yourdomain.com
      policy: bypass
    - domain: "*.yourdomain.com"
      policy: one_factor
 session:
  name: authelia_session
  domain: yourdomain.com
 regulation:
  max_retries: 3
  ban_time: 10m
 storage:
  local:
    path: /config/db.sqlite3
 notifier:
  filesystem:
    filename: /config/notification.txt
 EOF
 ```
 ### Service Management Commands
 #### User Operations Script (No Sudo Required)
 ```bash
 # Service status and control
 ./user-operations status              # View all service status
 ./user-operations status jellyfin     # View specific service
 ./user-operations logs jellyfin       # View service logs
 ./user-operations logs jellyfin -f    # Follow logs
 # Deployment operations
 ./user-operations deploy              # Deploy all services
 ./user-operations stop               # Stop all services
 ./user-operations restart            # Restart all services
 ./user-operations restart jellyfin   # Restart specific service
 # Update operations
 ./user-operations update             # Update all containers
 ./user-operations update jellyfin    # Update specific container
 ```
 #### Direct Docker Compose Commands
 ```bash
 cd ~/hops
 # Service management
 docker compose ps                          # List services
 docker compose up -d                       # Start all services
 docker compose down                        # Stop all services
-docker compose restart                      # Restart all services
+docker compose restart [service]           # Restart a service
-docker compose restart jellyfin             # Restart specific service
+docker compose logs -f [service]           # Follow logs
-
+docker compose logs --tail=100 [service]   # Last 100 lines
 # Logs and monitoring
 docker compose logs                          # View all logs
 docker compose logs -f jellyfin             # Follow specific service logs
 docker compose logs --tail=100 sonarr       # Last 100 lines
 # Updates and maintenance
 docker compose pull                        # Pull new images
 docker compose up -d --force-recreate      # Recreate containers
 docker compose down && docker compose up -d # Full restart
 # Resource monitoring
 docker stats                               # Real-time resource usage
 docker system df                           # Disk usage
 docker system prune                        # Clean unused data
 ```
-### New Modular Architecture
+## Firewall
-HOPS v3.1.0+ introduces a modular library system:
+HOPS configures UFW automatically on Linux. Manual management:
 ```
 hops/
 ├── lib/                    # Shared libraries
 │   ├── common.sh          # Logging, UI, utilities
 │   ├── system.sh          # OS detection, requirements
 │   ├── docker.sh          # Docker operations
 │   ├── security.sh        # Security functions
 │   ├── validation.sh      # Input validation
 │   ├── secrets.sh         # Secret management
 │   └── privileges.sh      # Privilege separation
 ├── setup                  # Main installation wrapper
 ├── privileged-setup       # Root-only operations
 ├── user-operations        # User operations
 ├── services-improved      # Enhanced service definitions
 └── hops                  # Main script
 ```
 #### Using Library Functions
 ```bash
 # Source libraries in custom scripts
 source lib/common.sh
 source lib/system.sh
 # Use logging functions
 log "INFO" "Starting custom operation"
 warning "This is a warning message"
 error_exit "Fatal error occurred"
 # Use system functions
 detect_os
 check_system_requirements 2 10  # 2GB RAM, 10GB disk
 # Use validation functions
 validate_port "8080"
 validate_domain "example.com"
 ```
 ## 🔒 Security Features & Hardening
 ### Automatic Security Hardening
 HOPS automatically implements several security measures:
 #### Firewall Configuration (Linux)
 ```bash
 # UFW rules automatically created
 sudo ufw status
 # Manual firewall management
 sudo ufw allow 8096/tcp comment "Jellyfin"
-sudo ufw allow 9000/tcp comment "Portainer"
+sudo ufw delete allow 8096/tcp
 sudo ufw delete allow 8096/tcp  # Remove rule
 ```
-#### File Permissions
+## File Permissions
 ```bash
 # Automatic permission hardening
 # Secrets: 600 (owner read/write only)
 # Configs: 644 (owner write, group/other read)
 # Scripts: 755 (executable)
-# Manual permission fixes
+```bash
 chmod 600 ~/hops/.env
 chmod 644 ~/hops/docker-compose.yml
 chmod 755 ~/hops/user-operations
 ```
 #### Network Isolation
 ```bash
 # Docker network isolation
 docker network ls | grep homelab
 docker network inspect homelab
 # View network configuration
 docker compose config | grep network
 ```
 ### Security Auditing
 ```bash
 # Run security audit
 ./lib/security.sh audit
 # Check for security issues
 ./lib/security.sh check-passwords
 ./lib/security.sh check-permissions
 ./lib/security.sh check-firewall
 # Security recommendations
 ./lib/security.sh recommendations
 ```
 ### SSL/TLS Configuration
 #### Traefik SSL
 Traefik automatically handles SSL certificates with Let's Encrypt:
 ```bash
 # Check certificate status
 docker compose logs traefik | grep -i certificate
 # Manual certificate renewal (if needed)
 docker compose restart traefik
 ```
 #### Custom SSL Certificates
 ```bash
 # For custom certificates, place in:
 # ~/hops/config/traefik/certs/
 # - yourdomain.com.crt
 # - yourdomain.com.key
 # Update Traefik configuration to use custom certs
 ```
 ## 🆘 Troubleshooting
 ### Common Issues & Solutions
 #### Docker Issues
 **Docker Not Starting:**
 ```bash
 # Check Docker status
 systemctl status docker
 # Restart Docker
 sudo systemctl restart docker
 # Check Docker logs
 journalctl -u docker --since "1 hour ago"
 # Reinstall Docker (Linux)
 curl -fsSL https://get.docker.com | sh
 sudo usermod -aG docker $USER
 newgrp docker
 ```
 **Docker Compose Errors:**
 ```bash
 # Validate compose file
 docker compose config
 # Check for syntax errors
 docker compose config --quiet
 # Force recreate containers
 docker compose up -d --force-recreate
 ```
 #### Service-Specific Issues
 **Service Won't Start:**
 ```bash
 # Check service logs
 docker compose logs [service-name]
 # Check container status
 docker compose ps
 # Restart service
 docker compose restart [service-name]
 # Check port conflicts
 sudo lsof -i :[port-number]
 ```
 **Permission Issues:**
 ```bash
 # Fix ownership (Linux)
 sudo chown -R $USER:$USER /opt/appdata
 sudo chown -R $USER:$USER /mnt/media
 sudo chown -R $USER:$USER ~/hops
 # Fix ownership (macOS)
 sudo chown -R $USER:$USER ~/hops/config
 sudo chown -R $USER:$USER ~/hops/media
 # Check PUID/PGID values
 id $USER  # Should match PUID/PGID in .env
 ```
 **Database Issues:**
 ```bash
 # Reset service database (example: Sonarr)
 docker compose down sonarr
 rm -rf ~/hops/config/sonarr/sonarr.db*  # macOS
 rm -rf /opt/appdata/sonarr/sonarr.db*   # Linux
 docker compose up -d sonarr
 ```
 #### Network Issues
 **Can't Access Services:**
 ```bash
 # Check if services are running
 docker compose ps
 # Check port mapping
 docker compose port jellyfin 8096
 # Check firewall (Linux)
 sudo ufw status
 # Check local firewall (macOS)
 # System Preferences → Security & Privacy → Firewall
 # Find container IP
 docker inspect jellyfin | grep IPAddress
 ```
 **Reverse Proxy Issues:**
 ```bash
 # Check proxy logs
 docker compose logs traefik
 docker compose logs nginx-proxy-manager
 # Verify DNS resolution
 nslookup yourdomain.com
 # Check certificate status
 openssl s_client -connect yourdomain.com:443 -servername yourdomain.com
 ```
 #### Platform-Specific Issues
 **macOS Issues:**
 ```bash
 # Docker Desktop not starting
 open /Applications/Docker.app
 # Homebrew issues
 brew doctor
 brew update && brew upgrade
 # Fix keychain authentication
 security unlock-keychain ~/Library/Keychains/login.keychain
 ```
 **Windows/WSL2 Issues:**
 ```bash
 # WSL2 not starting
 wsl --shutdown
 wsl -d Ubuntu-22.04
 # Docker Desktop WSL2 integration
 # Check Docker Desktop → Settings → Resources → WSL Integration
 # File permission issues
 # Ensure files are in WSL2 filesystem, not /mnt/c/
 ```
 ### Log Analysis
 #### Log Locations
 - **Installation Logs**:
  - Linux: `/var/log/hops/`
  - macOS: `/usr/local/var/log/hops/`
  - Windows: `~/hops/logs/`
 - **Service Logs**: `docker compose logs [service-name]`
 - **System Logs**: `journalctl -u docker`
 #### Log Analysis Commands
 ```bash
 # HOPS installation logs
 sudo tail -f /var/log/hops/hops-main-*.log
 # Service logs with filtering
 docker compose logs jellyfin | grep -i error
 docker compose logs --since="1h" sonarr
 docker compose logs --tail=100 radarr
 # System resource logs
 dmesg | grep -i memory
 journalctl --since="1 hour ago" | grep docker
 ```
 ### Recovery Procedures
 #### Service Recovery
 ```bash
 # Stop problematic service
 docker compose stop [service-name]
 # Remove container (keeps data)
 docker compose rm [service-name]
 # Recreate service
 docker compose up -d [service-name]
 # Full service reset (destroys data)
 docker compose down [service-name]
 rm -rf /path/to/service/config
 docker compose up -d [service-name]
 ```
 #### Complete System Recovery
 ```bash
 # Stop all services
 docker compose down
 # Backup current state
 sudo tar -czf hops-backup-$(date +%Y%m%d).tar.gz ~/hops /opt/appdata
 # Clean Docker system
 docker system prune -a
 docker volume prune
 # Restart from backup
 cd ~/hops
 docker compose up -d
 # Or reinstall HOPS
 sudo ./uninstall
 sudo ./setup
 ```
 ## 📊 Performance Tuning
 ### Resource Monitoring
 ```bash
 # Container resource usage
 docker stats
 # System resource usage
 htop
 iotop
 free -h
 df -h
 # Service-specific monitoring
 docker compose exec portainer sh
 # Access Portainer for detailed monitoring
 ```
 ### Optimization Strategies
 #### For Low-Resource Systems (2-4GB RAM)
 ```bash
 # Recommended minimal stack
 # - Jellyfin (media server)
 # - qBittorrent (download)
 # - Sonarr (TV management)
 # - Portainer (monitoring)
 # Resource limits in docker-compose.yml
 services:
  jellyfin:
    mem_limit: 1g
    cpus: '2'
  sonarr:
    mem_limit: 512m
    cpus: '1'
 ```
 #### For High-Performance Systems (8GB+ RAM)
 ```bash
 # Full stack deployment
 # Enable GPU transcoding
 # Use multiple download clients
 # Add monitoring stack
 # GPU support (Linux only)
 # Intel GPU passthrough automatically configured
 devices:
  - /dev/dri:/dev/dri
 ```
 #### Storage Optimization
 ```bash
 # Use SSD for application data
 # HDD for media storage
 # Separate Docker volumes
 # Example optimized storage layout
 /opt/appdata -> SSD
 /mnt/media   -> HDD array
 ~/hops       -> SSD
 ```
 ### Update Management
 ```bash
 # Automated updates with Watchtower
 # Configure update schedule
 WATCHTOWER_SCHEDULE=0 0 2 * * *  # 2 AM daily
 # Manual update process
 docker compose pull
 docker compose up -d
 # Rollback to previous version
 docker compose down
 docker tag service:latest service:backup
 docker pull service:previous
 docker compose up -d
 ```
 ## 🔧 Advanced Features
 ### Custom Service Definitions
 ```bash
 # Add custom services to docker-compose.yml
 services:
  custom-service:
    image: custom/image:latest
    container_name: custom-service
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
    volumes:
      - ${CONFIG_ROOT}/custom:/config
      - ${DATA_ROOT}:/data
    ports:
      - "8999:8999"
    restart: unless-stopped
    networks:
      - homelab
 ```
 ### Backup Automation
 ```bash
 # Automated backup script
 #!/bin/bash
 DATE=$(date +%Y%m%d_%H%M%S)
 BACKUP_DIR="/backup/hops"
 # Create backup directory
 mkdir -p "$BACKUP_DIR"
 # Backup configurations
 tar -czf "$BACKUP_DIR/config-$DATE.tar.gz" /opt/appdata
 # Backup compose files
 cp ~/hops/.env ~/hops/docker-compose.yml "$BACKUP_DIR/"
 # Backup encrypted secrets
 ./lib/secrets.sh backup "$BACKUP_DIR/secrets-$DATE.enc"
 # Clean old backups (keep 7 days)
 find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete
 ```
 ### Development & Testing
 ```bash
 # Development setup
 git clone https://github.com/skiercm/hops.git
 cd hops
 # Syntax validation
 bash -n lib/*.sh
 bash -n *.sh
 # Test service definitions
 ./services-improved list
 ./services-improved generate jellyfin
 # Test installation in VM/container
 # Use test environment before production deployment
 ```
 ---
-For installation guides, see [INSTALLATION.md](INSTALLATION.md).  
+For installation, see [INSTALLATION.md](INSTALLATION.md).
-For service information, see [SERVICES.md](SERVICES.md).
+For troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
@@ -1,78 +1,37 @@
 # Installation Guide
-This guide provides detailed installation instructions for all supported platforms.
+> **Note**: This document is being rebuilt alongside the 1.0.0 codebase.
 > Content will be expanded as features are stabilized.
-## 🔧 System Requirements
+## System Requirements
-### Minimum Requirements
+- **OS**: Ubuntu 20.04+, Debian 11+, or Linux Mint 20+ (x86_64)
- **RAM**: 2GB (4GB+ recommended)
+- **RAM**: 2GB minimum, 4GB+ recommended
- **Storage**: 10GB free space (more for media storage)
+- **Storage**: 10GB free (more for media)
 - **CPU**: 2 cores recommended
- **Network**: Internet connection required
+- **Access**: sudo privileges
-### Platform-Specific Requirements
+## Installation
 #### Linux (Ubuntu/Debian/Mint)
 - **OS**: Ubuntu 20.04+, Debian 11+, or Linux Mint 20+
 - **Architecture**: x86_64
 - **Access**: Root/sudo privileges
 - **Dependencies**: Automatically installed
 #### macOS
 - **OS**: macOS 11.0+ (Big Sur)
 - **Architecture**: Intel (x86_64) or Apple Silicon (ARM64)
 - **Access**: Admin privileges (sudo)
 - **Dependencies**: Homebrew and Docker Desktop installed automatically
 #### Windows (WSL2)
 - **OS**: Windows 10 (build 19041+) or Windows 11
 - **WSL**: WSL2 enabled with Ubuntu 20.04+ distribution
 - **Docker**: Docker Desktop with WSL2 backend
 - **Access**: Admin access for initial setup
 - **Architecture**: x86_64 with virtualization support
 - **BIOS**: Hyper-V and virtualization enabled
 ⚠️ **Note**: Windows support has limited testing. Proceed with caution and ensure backups.
 ## 🐧 Linux Installation
 ### Quick Install
 ```bash
-# Download HOPS
+git clone https://git.canadabot.net/canadabot/hops.git
 git clone https://github.com/skiercm/hops.git
 cd hops
-chmod +x hops install uninstall setup
+chmod +x hops install uninstall
 # Run installation
 sudo ./setup
 ```
 ### Manual Installation (Advanced)
 ```bash
 # Two-phase installation for enhanced security
 sudo ./privileged-setup              # Root operations
 ./user-operations generate <services> # User operations
 ./user-operations deploy             # Deploy services
 # Legacy method (still supported)
 sudo ./hops
 ```
-### What Gets Installed
+HOPS will install Docker automatically if not present, then walk you through
- Docker Engine (via official Docker script)
+selecting and deploying services interactively.
- Docker Compose
+
- Required system packages
+## Directory Structure
 - UFW firewall rules (automatic)
 - Service directories and permissions
 ### Directory Structure
 ```
-~/hops/                       # Main deployment directory
+~/hops/                  # Deployment directory
-├── docker-compose.yml        # Service definitions
+├── docker-compose.yml   # Generated service definitions
-├── .env                      # Environment variables
+├── .env                 # Environment variables and secrets
-└── logs/                     # Application logs
+└── logs/                # HOPS logs
-/opt/appdata/                 # Application configurations
+/opt/appdata/            # Application config data
 ├── jellyfin/
 ├── sonarr/
 └── [other services]/
@@ -84,282 +43,20 @@ sudo ./hops
 └── downloads/
 ```
-## 🍎 macOS Installation
+## Post-Installation
 ### Prerequisites Setup
 HOPS automatically handles dependency installation on macOS, but you can pre-install if desired:
 ```bash
-# Optional: Install Homebrew (will be done automatically)
+# Check service status
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+cd ~/hops && docker compose ps
-# Optional: Install Docker Desktop (will be done automatically)
+# View logs
-brew install --cask docker
+docker compose logs -f [service-name]
 ```
-### HOPS Installation
+# Access management interface
 ```bash
 # Download HOPS
 git clone https://github.com/skiercm/hops.git
 cd hops
 chmod +x hops install uninstall setup
 # Run installation with admin privileges
 sudo ./setup
 ```
 ### macOS-Specific Features
 - **Docker Desktop Integration**: Automatic installation and startup
 - **Keychain Authentication**: Secure Docker authentication
 - **User Directory Structure**: All files in user home directory
 - **Automatic Dependency Resolution**: Homebrew packages installed as needed
 ### Directory Structure (macOS)
 ```
 ~/hops/                       # Main deployment directory
 ├── docker-compose.yml        # Service definitions
 ├── .env                      # Environment variables
 ├── logs/                     # Application logs
 ├── config/                   # Application configurations
 │   ├── jellyfin/
 │   ├── sonarr/
 │   └── [other services]/
 └── media/                    # Media storage
    ├── movies/
    ├── tv/
    ├── music/
    └── downloads/
 ```
 ### Important Notes for macOS
 - **GPU Acceleration**: Not available (Docker containers cannot access macOS GPU)
 - **Firewall**: Manual configuration required (automatic UFW setup skipped)
 - **File Permissions**: Uses user's home directory for better compatibility
 - **Performance**: Excellent performance on both Intel and Apple Silicon
 ## 🪟 Windows Installation (WSL2)
 Windows support uses WSL2 (Windows Subsystem for Linux) for excellent Linux compatibility.
 ### Step 1: Enable WSL2
 ```powershell
 # Run in PowerShell as Administrator
 wsl --install
 # Restart computer when prompted
 ```
 ### Step 2: Install Ubuntu Distribution
 ```powershell
 # Install Ubuntu 22.04 LTS (recommended)
 wsl --install Ubuntu-22.04
 # Follow prompts to create username and password
 ```
 ### Step 3: Install Docker Desktop
 1. Download [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
 2. Enable WSL2 integration during installation
 3. Ensure "Use WSL 2 based engine" is enabled in Docker settings
 4. Enable integration with your Ubuntu distribution
 ### Step 4: Install HOPS
 ```bash
 # Launch Ubuntu from Start Menu or run: wsl -d Ubuntu-22.04
 cd ~
 git clone https://github.com/skiercm/hops.git
 cd hops
 chmod +x hops install uninstall setup
 # Run installation (same as Linux)
 sudo ./setup
 ```
 ### Windows-Specific Considerations
 #### File System Performance
 - **Always run HOPS from WSL2 filesystem** (`~/hops/`) for optimal performance
 - **Avoid Windows drives** (`/mnt/c/`) as they have significant performance penalties
 - WSL2 provides 95% of native Linux performance when using WSL2 filesystem
 #### Media Access
 Your Windows media can be accessed from WSL2:
 - `C:\Users\YourName\` → `/mnt/c/Users/YourName/`
 - External drives → `/mnt/d/`, `/mnt/e/`, etc.
 #### Service Access
 - **Web interfaces**: Accessible from Windows browsers using WSL2 IP or localhost
 - **File shares**: Available in Windows Explorer via `\\wsl.localhost\Ubuntu-22.04\home\username\hops\`
 - **Network**: Services are accessible from both Windows and WSL2
 #### Directory Structure (Windows/WSL2)
 ```
 # WSL2 filesystem (recommended location)
 ~/hops/                       # Main deployment directory
 ├── docker-compose.yml        # Service definitions
 ├── .env                      # Environment variables
 └── logs/                     # Application logs
 /opt/appdata/                 # Application configurations
 ├── jellyfin/
 ├── sonarr/
 └── [other services]/
 /mnt/media/                   # Media storage (can link to Windows drives)
 ├── movies/ -> /mnt/d/Movies/
 ├── tv/ -> /mnt/d/TV/
 ├── music/ -> /mnt/d/Music/
 └── downloads/
 ```
 ## 🔧 Installation Options
 ### Option 1: Secure Installation (Recommended)
 ```bash
 sudo ./setup
 ```
 - **Best Practice**: Separates privileged and user operations
 - **Enhanced Security**: Minimizes root access time
 - **User-Friendly**: Guided interactive setup
 ### Option 2: Manual Two-Phase Installation
 ```bash
 sudo ./privileged-setup               # Root-only operations
 ./user-operations generate [services] # Select and generate services
 ./user-operations deploy              # Deploy services
 ```
 - **Advanced Users**: Full control over each phase
 - **Automation**: Can be scripted for multiple deployments
 - **Security**: Clear separation of privileged operations
 ### Option 3: Legacy Installation
 ```bash
 sudo ./hops
 ```
 - **Compatibility**: Original installation method
 - **Full-Featured**: Complete management interface
 - **Reliability**: Extensively tested method
-## 🔍 Post-Installation Verification
+## Getting Help
-### Check Service Status
+- Issues: [git.canadabot.net/canadabot/hops/issues](https://git.canadabot.net/canadabot/hops/issues)
-```bash
+- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
 # Via HOPS management interface
 sudo ./hops
 # Select option 4: Service Status
 # Via user operations
 ./user-operations status
 # Direct Docker commands
 cd ~/hops
 docker compose ps
 ```
 ### Access Service URLs
 After installation, HOPS provides URLs for all services:
 ```
 📱 Access your services at:
   ● Jellyfin     http://192.168.1.100:8096
   ● Sonarr       http://192.168.1.100:8989
   ● Radarr       http://192.168.1.100:7878
   ● Portainer    http://192.168.1.100:9000
 ```
 ### Verify File Permissions
 ```bash
 # Check directory ownership
 ls -la ~/hops/
 ls -la /opt/appdata/ (Linux) or ~/hops/config/ (macOS)
 ls -la /mnt/media/ (Linux) or ~/hops/media/ (macOS)
 ```
 ## 🆘 Troubleshooting Installation
 ### Common Issues
 #### Docker Installation Failed
 ```bash
 # Check Docker status
 systemctl status docker
 # Restart Docker
 sudo systemctl restart docker
 # Reinstall Docker (Linux)
 curl -fsSL https://get.docker.com | sh
 ```
 #### Permission Denied Errors
 ```bash
 # Fix directory ownership
 sudo chown -R $USER:$USER ~/hops/
 sudo chown -R $USER:$USER /opt/appdata/ (Linux)
 sudo chown -R $USER:$USER ~/hops/config/ (macOS)
 ```
 #### Port Conflicts
 ```bash
 # Check what's using a port
 sudo lsof -i :PORT_NUMBER
 # Kill conflicting process
 sudo kill -9 PID
 ```
 #### WSL2 Issues (Windows)
 ```bash
 # Restart WSL2
 wsl --shutdown
 wsl -d Ubuntu-22.04
 # Check Docker Desktop WSL2 integration
 # Go to Docker Desktop Settings → Resources → WSL Integration
 ```
 ### Log Locations
 - **Installation Logs**: 
  - Linux: `/var/log/hops/`
  - macOS: `/usr/local/var/log/hops/`
  - Windows: `~/hops/logs/`
 - **Service Logs**: `docker compose logs [service-name]`
 - **System Logs**: `journalctl -u docker`
 ### Getting Help
 1. **Built-in Help**: `sudo ./hops` → Option 7
 2. **Check Logs**: Review installation logs for errors
 3. **Verify Prerequisites**: Ensure all system requirements are met
 4. **Docker Status**: Confirm Docker is running and accessible
 5. **GitHub Issues**: Report persistent issues with logs
 ## 🔄 Backup Strategy
 ### Before Installation
 ```bash
 # Backup existing media and configs
 sudo tar -czf homelab-backup-$(date +%Y%m%d).tar.gz \
  /path/to/your/media \
  /path/to/your/configs
 ```
 ### After Installation
 ```bash
 # Backup HOPS configuration
 sudo tar -czf hops-config-backup-$(date +%Y%m%d).tar.gz \
  ~/hops \
  /opt/appdata (Linux) or ~/hops/config (macOS)
 ```
 ## 📊 Performance Optimization
 ### During Installation
 - **SSD Storage**: Install on SSD for better performance
 - **Sufficient RAM**: Ensure adequate memory for selected services
 - **Network Speed**: Faster internet improves Docker image downloads
 ### After Installation
 - **Monitor Resources**: Use Portainer to monitor CPU, RAM, and disk usage
 - **Optimize Services**: Start with fewer services, add more gradually
 - **Storage Configuration**: Use dedicated drives for media storage
 ---
 For additional help, see [ADVANCED.md](ADVANCED.md) for configuration and troubleshooting details.
@@ -1,314 +1,95 @@
-# HOPS Troubleshooting Guide
+# Troubleshooting
-This document provides solutions to common issues encountered when installing and running HOPS.
+## Docker Not Starting
 ## Docker Repository Issues
 ### Linux Mint Docker Repository Error
 **Symptoms:**
 ```
 E: The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file.
 N: Updating from such a repository can't be done securely, and is therefore disabled by default.
 ```
 **Root Cause:**
 Linux Mint uses its own codenames (e.g., "xia", "vera", "vanessa") that don't exist in Docker's Ubuntu repositories. Docker only supports Ubuntu codenames like "noble", "jammy", "focal".
 **Solution:**
 This issue has been resolved in HOPS v3.3.0+. The system now automatically detects the correct Ubuntu codename for Linux Mint installations using `UBUNTU_CODENAME` from `/etc/os-release`.
 **Manual Fix (if needed):**
 1. **Clean existing Docker repositories:**
   ```bash
   sudo rm -f /etc/apt/sources.list.d/docker*
   sudo rm -f /etc/apt/sources.list.d/*docker*
   sudo rm -f /usr/share/keyrings/docker*
   sudo rm -f /etc/apt/keyrings/docker*
   sudo apt clean
   ```
 2. **Verify Ubuntu codename detection:**
   ```bash
   grep '^UBUNTU_CODENAME=' /etc/os-release
   # Should return: UBUNTU_CODENAME=noble (for Linux Mint 22.x)
   ```
 3. **Update HOPS to latest version:**
   ```bash
   cd ~/hops
   git pull
   sudo ./hops --update
   ```
 ### Docker Installation Fails
 **Symptoms:**
 - `Package 'docker-ce' has no installation candidate`
 - `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`
 **Solutions:**
 1. **Check Docker service status:**
 ```bash
 sudo systemctl status docker
-   sudo systemctl status docker.socket
+sudo systemctl restart docker
 journalctl -u docker --since "1 hour ago"
 ```
-2. **Fix missing Docker group:**
+If Docker is missing or broken:
 ```bash
-   sudo groupadd docker
+curl -fsSL https://get.docker.com | sh
 sudo usermod -aG docker $USER
   sudo chown root:docker /var/run/docker.sock
   ```
 3. **Start Docker services:**
   ```bash
   sudo systemctl start docker.socket
   sudo systemctl start docker
   sudo systemctl enable docker
   ```
 4. **Verify Docker installation:**
   ```bash
   sudo docker --version
   sudo docker compose version
   sudo docker info
   ```
 ## Directory and Permission Issues
 ### Homelab Directory Not Found
 **Symptoms:**
 ```
 ERROR: Homelab directory not found: /root/hops
 ```
 **Root Cause:**
 When running with `sudo`, the script may look for files in `/root/hops` instead of the user's home directory.
 **Solution:**
 This issue has been resolved in HOPS v3.3.0+. The system now properly detects the original user's home directory when running with sudo.
 **Manual Workaround:**
 ```bash
 # Ensure you're in the correct directory
 cd ~/hops
 sudo ./hops
 ```
 ### Permission Denied Errors
 **Symptoms:**
 - Permission denied accessing Docker socket
 - Cannot create directories in `/opt/appdata`
 **Solutions:**
 1. **Fix Docker permissions:**
   ```bash
   sudo usermod -aG docker $USER
   # Log out and log back in, or run:
 newgrp docker
 ```
-2. **Fix directory permissions:**
+## Linux Mint: Docker Repository Error
 **Symptom:** `The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file`
 Linux Mint uses its own codenames that Docker's repo doesn't recognise. HOPS
 detects the underlying Ubuntu codename via `UBUNTU_CODENAME` in `/etc/os-release`.
 Manual fix:
 ```bash
 sudo rm -f /etc/apt/sources.list.d/docker* /etc/apt/keyrings/docker*
 sudo apt clean
 grep '^UBUNTU_CODENAME=' /etc/os-release   # confirm value is present
 sudo ./hops                                 # re-run installation
 ```
 ## Permission Denied
 ```bash
 # Docker socket access
 sudo usermod -aG docker $USER
 newgrp docker
 # Directory ownership
 sudo chown -R $USER:$USER ~/hops
-   sudo chmod -R 755 ~/hops
+sudo chown -R $USER:$USER /opt/appdata
 ```
-## Service Access Issues
+## Service Won't Start
 ### Cannot Access Service Web UI
 **Symptoms:**
 - Service shows as running but web UI is not accessible
 - Connection refused errors
 **Solutions:**
 1. **Check container status:**
 ```bash
 cd ~/hops
-   sudo docker compose ps
+docker compose logs [service-name]
-   sudo docker compose logs [service-name]
+docker compose ps
 docker compose restart [service-name]
 ```
-2. **Verify port availability:**
+## Port Already in Use
 ```bash
-   sudo netstat -tlnp | grep :8989  # For Sonarr
+sudo lsof -i :[port]
-   sudo ss -tlnp | grep :8989       # Alternative command
+sudo ss -tlnp | grep :[port]
 ```
-3. **Check firewall settings:**
+## Cannot Access Service Web UI
-   ```bash
+
-   sudo ufw status
+1. Confirm container is running: `docker compose ps`
-   # If needed, allow ports:
+2. Check for port conflicts (above)
-   sudo ufw allow 8989  # Example for Sonarr
+3. Check firewall: `sudo ufw status`
-   ```
+4. Allow port if needed: `sudo ufw allow [port]/tcp`
-
+
-4. **Restart services:**
+## Docker Network Errors
-   ```bash
+
   cd ~/hops
   sudo docker compose restart [service-name]
   ```
 ## Network Issues
 ### Docker Network Creation Fails
 **Symptoms:**
 - `Error response from daemon: network with name [network] already exists`
 - Network connectivity issues between containers
 **Solutions:**
 1. **List existing networks:**
   ```bash
   sudo docker network ls
   ```
 2. **Remove conflicting networks:**
 ```bash
 # Remove conflicting networks and recreate
 sudo docker network rm traefik homelab
 cd ~/hops && docker compose up -d
 ```
-3. **Recreate networks:**
+## Log Locations
   ```bash
   cd ~/hops
   sudo docker compose up -d
   ```
-## System Requirements
+- **HOPS logs**: `/var/log/hops/hops-main-*.log`
 - **Service logs**: `docker compose logs [service-name]`
 - **System logs**: `journalctl -u docker`
-### Insufficient Resources
+## Reporting Issues
-**Symptoms:**
+Collect this info before reporting:
 - Services randomly stopping
 - Out of memory errors
 - Slow performance
 **Solutions:**
 1. **Check system resources:**
   ```bash
   free -h    # Memory usage
   df -h      # Disk usage
   top        # CPU and memory usage
   ```
 2. **Minimum requirements:**
   - RAM: 2GB minimum, 4GB+ recommended
   - Disk: 10GB minimum, 50GB+ recommended for media
   - CPU: 2 cores minimum
 3. **Optimize services:**
   - Disable unnecessary services
   - Adjust container resource limits
   - Use external storage for media files
 ## Getting Help
 ### Log Files
 Check HOPS log files for detailed error information:
 **Linux:**
 ```bash
 sudo tail -f /var/log/hops/hops-main-*.log
 ```
 **macOS:**
 ```bash
 sudo tail -f /usr/local/var/log/hops/hops-main-*.log
 ```
 ### Docker Compose Logs
 ```bash
 cd ~/hops
 sudo docker compose logs -f [service-name]
 ```
 ### System Information
 When reporting issues, include:
 ```bash
 # System information
 lsb_release -a
 uname -a
 docker --version
 docker compose version
 # HOPS version
 ./hops --version
-
+cd ~/hops && docker compose ps
 # Container status
 cd ~/hops && sudo docker compose ps
 ```
-### Reporting Issues
+Report at: [git.canadabot.net/canadabot/hops/issues](https://git.canadabot.net/canadabot/hops/issues)
 1. Check this troubleshooting guide first
 2. Search existing [GitHub Issues](https://github.com/skiercm/hops/issues)
 3. Create a new issue with:
   - Complete error messages
   - System information (above commands)
   - Steps to reproduce
   - Log file excerpts
 ## Recovery Commands
 ### Complete Reset
 If HOPS installation is completely broken:
 ```bash
 # Stop all containers
 cd ~/hops && sudo docker compose down
 # Remove containers and images (CAUTION: This removes all data)
 sudo docker system prune -a --volumes
 # Clean up repositories
 sudo rm -f /etc/apt/sources.list.d/docker*
 sudo apt clean
 # Reinstall HOPS
 cd ~/hops
 git pull
 sudo ./hops
 ```
 ### Partial Reset
 To reset only HOPS configuration:
 ```bash
 # Stop services
 cd ~/hops && sudo docker compose down
 # Remove generated files
 rm -f ~/hops/docker-compose.yml ~/hops/.env
 # Restart HOPS
 sudo ./hops
 ```
 ---
 ## Version History
 - **v3.3.0+**: Fixed Linux Mint Docker repository detection
 - **v3.2.0+**: Added macOS support and improved error handling
 - **v3.1.0+**: Initial multi-platform support
 For the latest updates and fixes, always ensure you're running the latest version:
 ```bash
 cd ~/hops
 sudo ./hops --update
 ```