Add comprehensive troubleshooting documentation and update summary

- Update summary7-19.txt with complete resolution of Linux Mint Docker issue
- Add TROUBLESHOOTING.md with detailed solutions for common HOPS issues
- Document the critical case sensitivity bug fix (LinuxMint vs Linuxmint)
- Provide manual fixes for Docker service and directory detection issues
- Include recovery commands and system requirements

This resolves the Linux Mint repository detection issue completely.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

ADVANCED.md

@@ -0,0 +1,715 @@
+# Advanced Configuration & Troubleshooting
+
+This guide covers advanced HOPS configuration, troubleshooting, security features, and system administration.
+
+## 🔧 Advanced Configuration
+
+### Environment Variables
+
+HOPS uses both encrypted secret management and traditional environment files for configuration.
+
+#### Encrypted Secret Management (v3.1.0+)
+```bash
+# Initialize secret management
+./lib/secrets.sh init
+
+# 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 (Linux)
+CONFIG_ROOT=/opt/appdata     # App configurations (Linux)
+
+# macOS paths (automatically set)
+DATA_ROOT=/Users/username/hops/media
+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
+
+#### 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 jellyfin             # Restart specific service
+
+# 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
+
+HOPS v3.1.0+ introduces a modular library system:
+
+```
+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  # Remove rule
+```
+
+#### 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
+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 service information, see [SERVICES.md](SERVICES.md).

CHANGELOG.md

@@ -0,0 +1,257 @@
+# Changelog
+
+All notable changes to HOPS will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.3.0] - 2025-01-19
+
+### Added
+- **🔄 Automatic Updates**: Git-based update mechanism with backup functionality
+- **📱 Command Line Interface**: New flags for update management
+  - `--update`: Update HOPS to latest version automatically
+  - `--check-updates`: Check for available updates (returns exit code 1 if updates available)
+  - `--version`: Display current version information
+  - `--help`: Show comprehensive help and usage information
+- **🛡️ Safe Updates**: Automatic backup of local changes before updating
+- **📋 Change Tracking**: Display recent changes and version comparison during updates
+- **🎛️ Interactive Updates**: Update checking integrated into main menu (option 6)
+
+### Changed
+- **Version Numbering**: Updated to v3.3.0 across all components
+- **Menu Structure**: Added "Check for Updates" as menu option 6, shifted other options
+- **Documentation**: Updated README.md and CLAUDE.md with new update functionality
+- **Color Code Handling**: Removed duplicate color definitions, now sourced from lib/common.sh
+
+### Fixed
+- **Script Compatibility**: Resolved readonly variable conflicts between main script and libraries
+- **Update Process**: Robust error handling and rollback for failed updates
+- **Exit Codes**: Proper exit codes for command-line operations
+
+### Security
+- **Backup Protection**: Local changes are automatically backed up before any updates
+- **Git Validation**: Comprehensive validation that HOPS is in a git repository before updates
+- **Privilege Handling**: Updates require appropriate privileges (root/sudo) for system changes
+
+## [3.2.0] - 2024-07-18
+
+### Added
+- **Caddy Support**: Added Caddy reverse proxy as a service option
+- **Enhanced macOS Compatibility**: Comprehensive improvements for macOS installation and operation
+- **Docker Desktop Integration**: Improved Docker Desktop startup and management on macOS
+- **Keychain Integration**: Proper Docker authentication with macOS keychain on macOS
+
+### Fixed
+- **User Directory Fixes**: All directories now use actual user home instead of root on macOS
+- **Password Generation**: Resolved `shuf` command and encoding issues on macOS
+- **Container Creation**: Fixed Docker Compose working directory and execution context issues
+- **Healthcheck Improvements**: Enhanced service health monitoring, particularly for Jellyseerr
+- **File Permissions**: Proper ownership of all directories and files across platforms
+- **Docker Compose Warnings**: Resolved version warnings and compatibility issues
+
+### Changed
+- **macOS File Structure**: Improved directory layout using user home instead of system directories
+- **Error Handling**: Enhanced error messages and troubleshooting information for macOS
+- **Documentation**: Updated platform-specific installation and configuration guides
+
+### Security
+- **Secure Authentication**: Enhanced Docker authentication methods on macOS
+- **File Ownership**: Improved file permission management across all platforms
+
+## [3.1.0-beta] - 2024-06-15
+
+### Added
+- **Encrypted Secret Management**: All passwords and sensitive data now encrypted with AES-256
+- **Input Validation**: Comprehensive validation preventing injection attacks
+- **Privilege Separation**: Root operations separated from user operations for enhanced security
+- **Pinned Container Versions**: All container images use specific versions, not `latest`
+- **Modular Architecture**: Shared code organized in `lib/` directory for better maintainability
+- **Cross-Platform Support**: Native support for Linux, macOS, and Windows (WSL2)
+- **Enhanced Error Handling**: Better error messages and recovery mechanisms
+- **Improved Service Definitions**: Standardized service generation with validation
+- **Complete Documentation**: Added `CLAUDE.md` for development guidance
+
+### Changed
+- **Installation Methods**: New secure installer `setup` script as recommended method
+- **Service Management**: New `user-operations` script for non-privileged service management
+- **Architecture**: Modular library system replacing monolithic scripts
+- **Security Model**: Clear separation between privileged and user operations
+
+### Security
+- **AES-256 Encryption**: All secrets stored encrypted with master key management
+- **Input Sanitization**: Comprehensive validation preventing code injection
+- **Container Security**: Pinned versions preventing supply chain attacks
+- **Privilege Minimization**: Reduced root access requirements
+
+## [3.0.0] - 2024-05-01
+
+### Added
+- **Cross-Platform Support**: Full support for Linux, macOS, and Windows (WSL2)
+- **Automatic Dependency Installation**: Docker and system requirements installed automatically
+- **Platform Detection**: Intelligent OS detection and platform-specific optimizations
+- **Enhanced Service Catalog**: Expanded service definitions with health checks
+- **Comprehensive Logging**: Detailed logging system for troubleshooting
+- **Service Health Monitoring**: Built-in health checks for all services
+- **Rollback Capabilities**: Automatic rollback on deployment failure
+
+### Changed
+- **Installation Process**: Streamlined installation with better user experience
+- **Directory Structure**: Platform-appropriate directory layouts
+- **Service Definitions**: Standardized Docker Compose patterns
+- **Error Handling**: Improved error messages and recovery procedures
+
+### Fixed
+- **Port Conflict Detection**: Better handling of port conflicts
+- **Permission Issues**: Improved file permission management
+- **Service Dependencies**: Enhanced dependency resolution
+
+## [2.1.0] - 2024-03-15
+
+### Added
+- **Huntarr Support**: Missing media discovery and automation
+- **Jellystat Support**: Jellyfin statistics and monitoring
+- **Watchtower Integration**: Automatic container updates
+- **Enhanced Monitoring**: Improved service status monitoring
+- **Backup Utilities**: Built-in backup and recovery tools
+
+### Changed
+- **Service Management**: Improved start/stop/restart functionality
+- **Log Viewing**: Enhanced centralized log viewing
+- **Configuration Management**: Better environment variable handling
+
+### Fixed
+- **Memory Usage**: Optimized resource usage for low-resource systems
+- **Startup Issues**: Resolved service startup race conditions
+- **Network Configuration**: Fixed Docker network isolation issues
+
+## [2.0.0] - 2024-02-01
+
+### Added
+- **Management Interface**: Comprehensive web-based management
+- **Security Hardening**: Automatic firewall configuration and secure passwords
+- **Service Templates**: Standardized service definitions
+- **Real-time Monitoring**: Live service status and resource monitoring
+- **User Interface**: Menu-driven installation and management
+
+### Changed
+- **Architecture**: Complete rewrite with modular design
+- **Installation**: Simplified one-command installation
+- **Configuration**: Centralized configuration management
+
+### Breaking Changes
+- **Directory Structure**: New standardized directory layout
+- **Configuration Format**: Updated environment variable structure
+- **Service Names**: Standardized container and service naming
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- **Authelia Support**: Multi-factor authentication and SSO
+- **Nginx Proxy Manager**: Alternative reverse proxy option
+- **Enhanced SSL**: Automatic SSL certificate management
+- **Service Discovery**: Automatic service registration
+
+### Fixed
+- **Traefik Configuration**: Improved reverse proxy setup
+- **SSL Issues**: Resolved certificate generation problems
+- **Network Routing**: Fixed internal service communication
+
+## [1.1.0] - 2023-12-01
+
+### Added
+- **Traefik Integration**: Automatic reverse proxy with SSL
+- **Service Categories**: Organized services by function
+- **Dependency Management**: Automatic service dependency resolution
+- **Health Checks**: Service health monitoring and restart
+
+### Changed
+- **Service Definitions**: Improved Docker Compose templates
+- **Network Configuration**: Enhanced Docker networking
+
+## [1.0.0] - 2023-11-01
+
+### Added
+- **Initial Release**: Core HOPS functionality
+- **Service Support**: Basic *arr stack, download clients, and media servers
+- **Docker Integration**: Docker Compose based deployment
+- **Linux Support**: Ubuntu/Debian/Mint support
+- **Basic Management**: Simple service management interface
+
+### Features
+- **Automated Installation**: One-command deployment
+- **Service Selection**: Interactive service selection
+- **Basic Security**: Firewall rules and secure passwords
+- **Directory Management**: Automatic directory creation and permissions
+
+---
+
+## Version Support
+
+- **v3.3.x**: Current stable release with automatic update support
+- **v3.2.x**: Previous stable release, upgrade recommended
+- **v3.1.x**: Beta features, limited support
+- **v3.0.x**: Legacy support for critical bugs only
+- **v2.x and earlier**: No longer supported
+
+## Upgrade Path
+
+### From v3.2.x to v3.3.0 (Recommended - Automatic)
+```bash
+# Use built-in update system
+cd /path/to/hops
+sudo ./hops --update
+
+# Or use interactive menu
+sudo ./hops
+# Select option 6: Check for Updates
+```
+
+### From v3.1.x to v3.3.0 (Manual)
+```bash
+# Backup current installation
+sudo tar -czf hops-backup-$(date +%Y%m%d).tar.gz ~/hops /opt/appdata
+
+# Pull latest version
+cd ~/hops
+git pull origin main
+
+# Run upgrade
+sudo ./setup --upgrade
+```
+
+### From v3.0.x to v3.2.0
+```bash
+# Major version upgrade requires fresh installation
+# Backup data first
+sudo ./uninstall --keep-data
+sudo ./setup
+```
+
+### From v2.x to v3.2.0
+```bash
+# Migration script available
+sudo ./migrate-from-v2.sh
+```
+
+## Migration Notes
+
+### v3.2.0 Changes
+- **macOS Users**: Directory structure has changed, migration handled automatically
+- **Caddy Users**: Manual Caddyfile configuration required
+- **Configuration**: Encrypted secrets now default for new installations
+
+### v3.1.0 Changes
+- **Security**: All passwords moved to encrypted storage
+- **Architecture**: New modular library system
+- **Privileges**: Installation process now uses privilege separation
+
+### v3.0.0 Changes
+- **Cross-Platform**: New platform detection and configuration
+- **Directories**: Platform-specific directory structures
+- **Services**: Updated service definitions and health checks
+
+---
+
+For detailed upgrade instructions, see [INSTALLATION.md](INSTALLATION.md).  
+For breaking changes and migration help, see [ADVANCED.md](ADVANCED.md).

INSTALLATION.md

@@ -0,0 +1,365 @@
+# Installation Guide
+
+This guide provides detailed installation instructions for all supported platforms.
+
+## 🔧 System Requirements
+
+### Minimum Requirements
+- **RAM**: 2GB (4GB+ recommended)
+- **Storage**: 10GB free space (more for media storage)
+- **CPU**: 2 cores recommended
+- **Network**: Internet connection required
+
+### Platform-Specific Requirements
+
+#### 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://github.com/skiercm/hops.git
+cd hops
+chmod +x hops install uninstall setup
+
+# 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
+- Docker Engine (via official Docker script)
+- Docker Compose
+- Required system packages
+- UFW firewall rules (automatic)
+- Service directories and permissions
+
+### Directory Structure
+```
+~/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
+├── movies/
+├── tv/
+├── music/
+└── downloads/
+```
+
+## 🍎 macOS 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)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Optional: Install Docker Desktop (will be done automatically)
+brew install --cask docker
+```
+
+### HOPS Installation
+```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
+
+### Check Service Status
+```bash
+# 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.

README.md

@@ -1,623 +1,125 @@
 # HOPS - Homelab Orchestration Provisioning Script
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/Version-3.2.0-blue.svg)]()
+[![Version](https://img.shields.io/badge/Version-3.3.0-blue.svg)]()
 [![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-orange.svg)]()
 
-**HOPS** is a comprehensive, automated deployment solution for popular homelab applications. It simplifies the process of setting up and managing Docker-based services including media servers, download clients, monitoring tools, and more.
+**HOPS** is a comprehensive automation tool for deploying homelab infrastructure using Docker Compose. Deploy and manage popular homelab services including media servers, download clients, monitoring tools, and more through an intuitive menu-driven interface.
 
-## ⚠️ Important Notices
+## ⚠️ Important: Beta Software
+**HOPS is beta software**. Always backup your data before installation and test in non-production environments first.
 
-### 🚧 Development Status
-**HOPS is under active development** and should be considered beta software. While core functionality is stable and tested, new features and improvements are being added regularly.
+**Platform Status:**
+- **Linux**: ✅ Stable and extensively tested
+- **macOS**: ✅ Recently improved with v3.2.0 fixes  
+- **Windows (WSL2)**: ⚠️ Limited testing
 
-### 🖥️ Platform Testing Status
-- **Linux (Ubuntu/Debian/Mint)**: ✅ Extensively tested and stable
-- **macOS**: ✅ Recently improved with comprehensive compatibility fixes
-- **Windows (WSL2)**: ⚠️ **Limited testing** - Basic functionality works but may have undiscovered issues
+## 🆕 What's New in v3.3.0
+- **🔄 Automatic Updates**: Git-based update system with backup functionality
+- **📱 Command Line Interface**: `--update`, `--check-updates`, `--version`, `--help` flags
+- **🛡️ Safe Updates**: Automatic backup of local changes before updating
+- **📋 Change Tracking**: View recent changes and version comparison
 
-### 💾 Data Safety & Backups
-**IMPORTANT**: Always maintain regular backups of your data before using HOPS.
-
-- **Backup your media and configuration files** before installation
-- **Test in a non-production environment** first if possible
-- **HOPS is not responsible for any data loss** that may occur during installation or operation
-- **Docker operations can be destructive** - ensure you understand what services you're installing
-
-### 📋 Recommended Backup Strategy
-```bash
-# Before running HOPS, backup important directories
-sudo tar -czf homelab-backup-$(date +%Y%m%d).tar.gz /path/to/your/media /path/to/your/configs
-
-# After installation, backup HOPS configuration
-sudo tar -czf hops-config-backup-$(date +%Y%m%d).tar.gz ~/hops ~/.config/hops
-```
-
-## 🆕 What's New in v3.2.0
-
-### Major macOS Compatibility Improvements
-- **🍎 Enhanced macOS Support**: Comprehensive fixes for macOS installation and operation
-- **🔐 Keychain Integration**: Proper Docker authentication with macOS keychain
-- **👤 User Directory Fixes**: All directories now use actual user home instead of root
-- **🚀 Docker Desktop Integration**: Improved Docker Desktop startup and management
-- **⚡ Better Error Handling**: Enhanced error messages and troubleshooting for macOS
-
-### New Features
-- **🌐 Caddy Support**: Added Caddy reverse proxy as a service option (configuration not included)
-
-### Bug Fixes
-- **🔧 Fixed password generation**: Resolved `shuf` command and encoding issues on macOS
-- **🐳 Fixed container creation**: Resolved Docker Compose working directory issues
-- **🏥 Fixed healthchecks**: Improved Jellyseerr and other service health monitoring
-- **📁 Fixed file permissions**: Proper ownership of config and media directories
-
-### Previous in v3.1.0-beta
-- **🔐 Encrypted Secret Management**: All passwords and sensitive data now encrypted with AES-256
-- **🛡️ Input Validation**: Comprehensive validation preventing injection attacks
-- **⚡ Privilege Separation**: Root operations separated from user operations
-- **📌 Pinned Versions**: All container images use specific versions, not `latest`
-
-### New Architecture
-- **📚 Modular Libraries**: Shared code organized in `lib/` directory
-- **🔧 Enhanced Error Handling**: Better error messages and recovery mechanisms
-- **🎯 Improved Service Definitions**: Standardized service generation with validation
-- **📖 Documentation**: Complete `CLAUDE.md` for development guidance
-- **🍎 Cross-Platform Support**: Native support for Linux, macOS, and Windows (WSL2) with automatic dependency installation
-
-### Installation Methods
-- **🚀 New Secure Installer**: `sudo ./setup` - Recommended method
-- **⚙️ Manual Installation**: Separate privileged and user operations
-- **🔄 Legacy Support**: Original `hops.sh` still fully supported
-
-## 🎯 What is HOPS?
-
-HOPS (Homelab Orchestration Provisioning Script) automates the deployment of a complete homelab infrastructure using Docker Compose. It provides an intuitive menu-driven interface for selecting, configuring, and managing services with enterprise-grade features like:
-
-- **Automated dependency resolution**
-- **Security hardening and firewall configuration**
-- **Service health monitoring**
-- **Rollback capabilities on failure**
-- **Comprehensive logging**
-- **User-friendly management interface**
+### Previous Updates (v3.2.0)
+- **Enhanced macOS Support**: Docker Desktop integration, keychain authentication, user directory fixes
+- **Caddy Support**: Added reverse proxy option (user provides configuration)
+- **Bug Fixes**: Password generation, container creation, healthchecks, file permissions
+- **Security**: Encrypted secret management, input validation, privilege separation
 
 ## ✨ Key Features
 
-### 🚀 **Easy Installation**
-- One-command installation process
-- Automatic Docker installation and configuration
-- Interactive service selection
-- Intelligent dependency resolution
-- **NEW**: Privilege separation for enhanced security
-
-### 🔒 **Security First**
-- Automatic firewall configuration
-- Secure password generation with encryption
-- File permission hardening
-- Network isolation
-- **NEW**: AES-256 encrypted secret storage
-- **NEW**: Comprehensive input validation
-- **NEW**: Pinned container versions
-
-### 📊 **Management & Monitoring**
-- Real-time service status monitoring
-- Centralized log viewing
-- Easy service management (start/stop/restart)
-- Health checks and service verification
-- **NEW**: Modular architecture with shared libraries
-
-### 🔄 **Reliability**
-- Error handling with automatic rollback
-- Service dependency management
-- Port conflict detection
-- System requirements validation
-- **NEW**: Enhanced error handling with detailed context
+- **🚀 Easy Installation**: One-command setup with automatic Docker installation
+- **🔒 Security First**: Encrypted secrets, firewall configuration, input validation
+- **📊 Management**: Real-time monitoring, centralized logs, service control
+- **🔄 Auto-Updates**: Built-in update system with backup protection
+- **🔧 Reliability**: Error handling, rollback capabilities, dependency management
+- **🌐 Cross-Platform**: Linux, macOS, and Windows (WSL2) support
 
 ## 📱 Supported Services
 
-### 📺 Media Management (*arr Stack)
-- **Sonarr** - TV show management
-- **Radarr** - Movie management  
-- **Lidarr** - Music management
-- **Readarr** - eBook/audiobook management
-- **Bazarr** - Subtitle management
-- **Prowlarr** - Indexer management
-- **Tdarr** - Media transcoding
-- **Huntarr** - Missing media discovery and automation
+**Media Management**: Sonarr, Radarr, Lidarr, Readarr, Bazarr, Prowlarr, Tdarr, Huntarr  
+**Download Clients**: qBittorrent, Transmission, NZBGet, SABnzbd  
+**Media Servers**: Jellyfin, Plex, Emby, Jellystat  
+**Request Management**: Overseerr, Jellyseerr, Ombi  
+**Reverse Proxy**: Traefik, Nginx Proxy Manager, Caddy, Authelia  
+**Monitoring**: Portainer, Uptime Kuma, Watchtower  
 
-### ⬇️ Download Clients
-- **qBittorrent** - Feature-rich BitTorrent client
-- **Transmission** - Lightweight BitTorrent client
-- **NZBGet** - Efficient Usenet downloader
-- **SABnzbd** - Popular Usenet client
-
-### 🎞️ Media Servers
-- **Jellyfin** - Open-source media server
-- **Plex** - Popular media server platform
-- **Emby** - Feature-rich media server
-- **Jellystat** - Jellyfin statistics and monitoring
-
-### 🎛️ Request Management
-- **Overseerr** - Media request management for Plex
-- **Jellyseerr** - Media request management for Jellyfin
-- **Ombi** - Media request platform
-
-### 🔒 Reverse Proxy & Security
-- **Traefik** - Modern reverse proxy with automatic SSL
-- **Nginx Proxy Manager** - Easy-to-use reverse proxy
-- **Caddy** - Automatic HTTPS web server (*configuration not included*)
-- **Authelia** - Authentication and authorization server
-
-### 📈 Monitoring & Management
-- **Portainer** - Docker container management
-- **Uptime Kuma** - Service monitoring
-- **Watchtower** - Automatic container updates
+[View complete service list with support links →](SERVICES.md)
 
 ## 🔧 System Requirements
 
-### Minimum Requirements
-- **OS**: 
-  - **Linux**: Ubuntu 20.04+, Debian 11+, or Linux Mint 20+
-  - **macOS**: 11.0+ (Big Sur) with Intel or Apple Silicon
-  - **Windows**: 10/11 with WSL2 (Ubuntu 20.04+ distribution) ⚠️ *Limited testing*
-- **RAM**: 2GB (4GB+ recommended)
-- **Storage**: 10GB free space (more for media)
-- **CPU**: 2 cores recommended
-- **Network**: Internet connection required
+**Minimum**: 2GB RAM, 10GB storage, 2 CPU cores, internet connection
 
-### Prerequisites
+**Supported Platforms:**
+- **Linux**: Ubuntu 20.04+, Debian 11+, Linux Mint 20+ (x86_64, sudo access)
+- **macOS**: 11.0+ Big Sur, Intel/Apple Silicon (admin access, auto-installs Docker Desktop)
+- **Windows**: 10/11 with WSL2 + Ubuntu 20.04+ (limited testing, requires Docker Desktop)
 
-**Linux:**
-- Root/sudo access
-- x86_64 architecture
-- Internet connection
-
-**macOS:**
-- Admin access (sudo privileges)
-- Intel (x86_64) or Apple Silicon (ARM64)
-- Internet connection
-- Homebrew will be installed automatically if not present
-- Docker Desktop will be installed automatically if not present
-
-**Windows:**
-- Windows 10 (build 19041+) or Windows 11
-- WSL2 enabled with Ubuntu 20.04+ distribution
-- Docker Desktop with WSL2 backend
-- Admin access to install prerequisites
-- x86_64 processor with virtualization support
-- Hyper-V and virtualization enabled in BIOS
-
-## 🪟 Windows Installation (WSL2)
-
-HOPS runs on Windows through WSL2 (Windows Subsystem for Linux) with excellent compatibility and performance. This approach leverages the full Linux environment within Windows.
-
-### Prerequisites Setup
-
-**1. Enable WSL2:**
-```powershell
-# Run in PowerShell as Administrator
-wsl --install
-# Restart computer when prompted
-```
-
-**2. Install Ubuntu Distribution:**
-```powershell
-# Install Ubuntu 22.04 LTS (recommended)
-wsl --install Ubuntu-22.04
-# Set up username and password when prompted
-```
-
-**3. Install Docker Desktop:**
-- Download from [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
-- Enable WSL2 integration during installation
-- Ensure "Use WSL 2 based engine" is checked in Docker settings
-
-### HOPS Installation on WSL2
-⚠️ **Note**: WSL2 support has limited testing. Please proceed with caution and ensure you have backups.
-
-**1. Open WSL2 Terminal:**
-```bash
-# Launch Ubuntu from Start Menu or run:
-wsl -d Ubuntu-22.04
-```
-
-**2. Install HOPS (same as Linux):**
-```bash
-# Clone inside WSL2 filesystem (important for performance)
-cd ~
-git clone https://github.com/skiercm/hops.git
-cd hops
-chmod +x hops install uninstall setup
-
-# Run installation
-sudo ./setup
-```
-
-### ⚠️ Important Notes for Windows Users
-
-**File Location:** Always run HOPS from the WSL2 filesystem (`~/hops/`) for optimal performance. Avoid running from `/mnt/c/` (Windows drives).
-
-**Media Access:** Your Windows media folders can be accessed at:
-- `C:\Users\YourName\` → `/mnt/c/Users/YourName/`
-- External drives → `/mnt/d/`, `/mnt/e/`, etc.
-
-**Docker Integration:** Services will be accessible from both Windows and WSL2:
-- Web interfaces work from Windows browsers
-- File shares accessible from Windows Explorer via `\\wsl.localhost\Ubuntu-22.04\home\username\hops\`
-
-**Performance:** WSL2 provides 95% of native Linux performance when files are stored in the WSL2 filesystem.
+[View detailed installation guides →](INSTALLATION.md)
 
 ## 🚀 Quick Start
 
-### 1. Download HOPS
 ```bash
+# 1. Download HOPS
 git clone https://github.com/skiercm/hops.git
 cd hops
 chmod +x hops install uninstall setup
-```
 
-### 2. Run Installation (New Improved Method)
-```bash
-# Option 1: Use the new secure installation wrapper
+# 2. Run installation
 sudo ./setup
 
-# Option 2: Manual two-phase installation
-sudo ./privileged-setup  # Run as root
-./user-operations generate <services>  # Run as user
-./user-operations deploy  # Run as user
+# 3. Follow interactive setup to select services
 
-# Option 3: Legacy installation (still supported)
-sudo ./hops.sh
+# 4. Access your services
+# URLs will be provided after installation
 ```
 
-### 3. Follow the Interactive Setup
-- Select your desired services
-- Configure directories and timezone
-- Choose security options
-- Wait for automated deployment
+**Directory Structure:**
+- `~/hops/` - Main deployment (docker-compose.yml, .env, logs)  
+- `/opt/appdata/` (Linux) or `~/hops/config/` (macOS) - App configs
+- `/mnt/media/` (Linux) or `~/hops/media/` (macOS) - Media storage
 
-### 4. Access Your Services
-The installer will provide URLs for all deployed 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
-```
-
-## 📁 Default Directory Structure
-
-```
-~/hops/                       # Main deployment directory
-├── docker-compose.yml        # Service definitions
-├── .env                      # Environment variables
-└── logs/                     # Application logs
-
-/opt/appdata/                 # Application configurations
-├── jellyfin/
-├── sonarr/
-├── radarr/
-└── ...
-
-/mnt/media/                   # Media storage
-├── movies/
-├── tv/
-├── music/
-└── downloads/
-```
-
-## 🎛️ Management Interface
-
-HOPS includes a comprehensive management interface accessible through the main script:
+## 🎛️ Management
 
 ```bash
-sudo ./hops.sh
+# Access management interface
+sudo ./hops
+
+# Update HOPS
+sudo ./hops --update                  # Update to latest version
+sudo ./hops --check-updates           # Check for updates
+./hops --version                      # Show version
+./hops --help                         # Show help
+
+# Service operations (no sudo required)
+./user-operations status              # View service status
+./user-operations logs <service>      # View logs
+./user-operations deploy              # Deploy services
+./user-operations stop               # Stop all services
 ```
 
-### Available Options:
-1. **Install HOPS** - Deploy new services
-2. **Uninstall HOPS** - Complete removal with options
-3. **Manage Services** - Start/stop/restart services
-4. **Service Status** - Real-time service monitoring
-5. **Access Information** - Get service URLs and credentials
-6. **View Logs** - Centralized log viewing
-7. **Help & Documentation** - Built-in help system
-
-## 🔧 Advanced Configuration
-
-### Environment Variables
-Configuration is now stored encrypted for enhanced security:
-
-```bash
-# NEW: Encrypted secret management
-./lib/secrets.sh init                    # Initialize secret management
-./lib/secrets.sh create                  # Create encrypted environment
-./lib/secrets.sh update DOMAIN example.com  # Update values
-./lib/secrets.sh get PUID               # Get values
-./lib/secrets.sh list                   # List all keys
-
-# Legacy: Plaintext configuration in ~/hops/.env
-PUID=1000                     # User ID
-PGID=1000                     # Group ID
-TZ=America/New_York          # Timezone
-
-# Directory Configuration
-DATA_ROOT=/mnt/media         # Media storage
-CONFIG_ROOT=/opt/appdata     # App configurations
-
-# Security (now auto-generated and encrypted)
-DEFAULT_ADMIN_PASSWORD=...   # Generated secure password
-DEFAULT_DB_PASSWORD=...      # Database password
-
-# Optional: Custom domain
-DOMAIN=yourdomain.com
-ACME_EMAIL=admin@yourdomain.com
-```
-
-### Service-Specific Configuration
-
-#### Caddy Configuration
-**Important**: HOPS provides the Caddy container but **does not include Caddyfile configuration**. Users must provide their own Caddyfile.
-
-```bash
-# Create Caddy configuration directory
-mkdir -p ~/hops/config/caddy
-
-# Create your Caddyfile (example)
-cat > ~/hops/config/caddy/Caddyfile << 'EOF'
-# Example Caddyfile - customize as needed
-example.com {
-    reverse_proxy jellyfin:8096
-}
-
-api.example.com {
-    reverse_proxy overseerr:5055
-}
-EOF
-
-# Caddy will automatically handle HTTPS certificates
-# Documentation: https://caddyserver.com/docs/
-```
-
-**Configuration Scope**: HOPS installs and runs the Caddy container with proper volume mounts, but all routing, SSL, and proxy configuration is the user's responsibility.
-
-### Service Management Commands
-```bash
-# NEW: User operations script (runs without sudo)
-./user-operations status        # View service status
-./user-operations logs <service> # View service logs
-./user-operations deploy        # Deploy services
-./user-operations stop          # Stop all services
-
-# Legacy: Direct Docker Compose commands
-cd ~/hops
-docker compose ps                       # View running services
-docker compose logs -f [service-name]  # View logs
-docker compose restart [service-name]  # Restart specific service
-docker compose pull && docker compose up -d  # Update all services
-docker compose down                     # Stop all services
-```
-
-### New Architecture
-HOPS v3.1.0-beta introduces a modular architecture with shared libraries:
-
-```
-hops/
-├── lib/                    # NEW: Shared libraries
-│   ├── common.sh          # Logging, UI, utilities
-│   ├── system.sh          # System validation
-│   ├── docker.sh          # Docker operations
-│   ├── security.sh        # Security utilities
-│   ├── validation.sh      # Input validation
-│   ├── secrets.sh         # Secret management
-│   └── privileges.sh      # Privilege management
-├── setup                  # NEW: Installation wrapper
-├── privileged-setup       # NEW: Root-only operations
-├── user-operations        # NEW: User operations
-├── services-improved      # NEW: Enhanced service definitions
-└── hops.sh               # Legacy main script (still supported)
-```
-
-## 🔒 Security Features
-
-### Automatic Security Hardening
-- **Firewall Configuration**: Automatic UFW rules for service ports
-- **Secure Passwords**: Cryptographically secure password generation
-- **File Permissions**: Restrictive permissions on sensitive files
-- **Network Isolation**: Docker network segregation
-- **SSL/TLS**: Automatic certificate management with Traefik
-- **NEW**: AES-256 encrypted secret storage with master key management
-- **NEW**: Comprehensive input validation preventing injection attacks
-- **NEW**: Privilege separation (root vs user operations)
-- **NEW**: Pinned container versions preventing supply chain attacks
-
-### Post-Installation Security
-1. **Manage Encrypted Secrets**: Use `./lib/secrets.sh` for secure password management
-2. **Configure Reverse Proxy**: Set up Traefik or Nginx Proxy Manager
-3. **Enable Authentication**: Configure Authelia for additional security
-4. **Regular Updates**: Use Watchtower for automatic updates
-5. **Security Auditing**: Use `./lib/security.sh` for security checks
-
-## 🆘 Troubleshooting
-
-### Common Issues
-
-#### Port Conflicts
-```bash
-# Check for port conflicts
-sudo lsof -i :PORT_NUMBER
-
-# View HOPS service status
-sudo ./hops.sh
-# Select option 4: Service Status
-```
-
-#### Service Won't Start
-```bash
-# Check service logs
-cd ~/hops
-docker compose logs [service-name]
-
-# Restart service
-docker compose restart [service-name]
-```
-
-#### Permission Issues
-```bash
-# Fix ownership of data directories
-sudo chown -R $USER:$USER /mnt/media /opt/appdata
-```
-
-### Log Locations
-- **Installation Logs**: `/var/log/hops/`
-- **Service Logs**: `docker compose logs [service-name]`
-- **System Logs**: `journalctl -u docker`
-
-### Getting Help
-1. Check the built-in help: `sudo ./hops.sh` → Option 7
-2. Review logs in `/var/log/hops/`
-3. Verify Docker status: `systemctl status docker`
-4. Check service health: `docker compose ps`
-
-## 🔄 Backup and Recovery
-
-### Backup Important Data
-```bash
-# Backup configurations
-sudo tar -czf hops-config-backup.tar.gz /opt/appdata
-
-# Backup compose files
-cp ~/hops/.env ~/hops/docker-compose.yml /backup/location/
-```
-
-### Recovery
-```bash
-# Restore configurations
-sudo tar -xzf hops-config-backup.tar.gz -C /
-
-# Redeploy services
-cd ~/hops
-docker compose up -d
-```
-
-## 📊 Performance Tuning
-
-### For Low-Resource Systems
-- Start with fewer services initially
-- Monitor resource usage with Portainer
-- Consider using lightweight alternatives (Transmission vs qBittorrent)
-
-### For High-Performance Systems
-- Enable GPU transcoding in Jellyfin/Plex
-- Use SSD storage for application data
-- Configure multiple download clients for redundancy
-
-## 🤝 Contributing
-
-We welcome contributions! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Test thoroughly
-5. Submit a pull request
-
-### Development Setup
-```bash
-git clone https://github.com/skiercm/hops.git
-cd hops
-
-# Test syntax validation
-bash -n lib/*.sh
-bash -n *.sh
-
-# Test service definitions
-./services-improved list
-./services-improved generate jellyfin
-
-# Test new installation method
-sudo ./setup
-
-# Test legacy method
-sudo ./hops.sh
-```
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- **LinuxServer.io** for excellent Docker images
-- **Docker** for containerization platform
-- **The Servarr Team** for the *arr applications
-- **Jellyfin Project** for the open-source media server
-- All the amazing open-source projects that make HOPS possible
+[View advanced configuration and troubleshooting →](ADVANCED.md)
 
 ## 📞 Support
 
-### HOPS Support
-- **Documentation**: Check this README and built-in help
-- **Issues**: Report HOPS bugs via [GitHub Issues](https://github.com/skiercm/hops/issues)
-- **Community**: Join discussions in [GitHub Discussions](https://github.com/skiercm/hops/discussions)
+**HOPS Issues**: [GitHub Issues](https://github.com/skiercm/hops/issues) | [Discussions](https://github.com/skiercm/hops/discussions)
 
-### Service-Specific Support
+**Service Issues**: Contact individual service developers (links in [SERVICES.md](SERVICES.md))
 
-**⚠️ Important**: If you encounter issues with a specific service (configuration, features, bugs), please reach out to the respective service developers directly using the links below. HOPS only handles deployment automation - the individual services are maintained by their respective teams.
+**Contact HOPS for**: Installation/deployment issues, Docker Compose problems, cross-platform issues  
+**Contact Service Developers for**: Service configuration, features, service-specific bugs
 
-#### 📺 Media Management (*arr Stack)
-- **Sonarr**: [github.com/Sonarr/Sonarr](https://github.com/Sonarr/Sonarr) - TV series management
-- **Radarr**: [github.com/Radarr/Radarr](https://github.com/Radarr/Radarr) - Movie collection manager
-- **Lidarr**: [github.com/Lidarr/Lidarr](https://github.com/Lidarr/Lidarr) - Music collection manager
-- **Readarr**: [github.com/Readarr/Readarr](https://github.com/Readarr/Readarr) - E-book manager ⚠️ *Project retired*
-- **Bazarr**: [github.com/morpheus65535/bazarr](https://github.com/morpheus65535/bazarr) - Subtitle management
-- **Prowlarr**: [github.com/Prowlarr/Prowlarr](https://github.com/Prowlarr/Prowlarr) - Indexer manager
-- **Tdarr**: [github.com/HaveAGitGat/Tdarr](https://github.com/HaveAGitGat/Tdarr) - Media transcoding
-- **Huntarr**: [github.com/plexguide/Huntarr.io](https://github.com/plexguide/Huntarr.io) - Missing media discovery
+## 📄 Documentation
 
-#### ⬇️ Download Clients
-- **qBittorrent**: [github.com/qbittorrent/qBittorrent](https://github.com/qbittorrent/qBittorrent) - BitTorrent client
-- **Transmission**: [github.com/transmission/transmission](https://github.com/transmission/transmission) - BitTorrent client
-- **NZBGet**: [github.com/nzbget/nzbget](https://github.com/nzbget/nzbget) - Usenet downloader
-- **SABnzbd**: [github.com/sabnzbd/sabnzbd](https://github.com/sabnzbd/sabnzbd) - Usenet downloader
+- [INSTALLATION.md](INSTALLATION.md) - Detailed installation guides for all platforms
+- [SERVICES.md](SERVICES.md) - Complete service list with support links  
+- [ADVANCED.md](ADVANCED.md) - Configuration, troubleshooting, security
+- [CHANGELOG.md](CHANGELOG.md) - Version history and changes
 
-#### 🎞️ Media Servers
-- **Jellyfin**: [github.com/jellyfin/jellyfin](https://github.com/jellyfin/jellyfin) - Free media server
-- **Plex**: [github.com/plexinc/pms-docker](https://github.com/plexinc/pms-docker) - Docker container repo
-- **Emby**: [github.com/MediaBrowser/Emby](https://github.com/MediaBrowser/Emby) - Personal media server
+## 📄 License
 
-#### 🎛️ Request Management
-- **Overseerr**: [github.com/sct/overseerr](https://github.com/sct/overseerr) - Media requests for Plex
-- **Jellyseerr**: [github.com/fallenbagel/jellyseerr](https://github.com/fallenbagel/jellyseerr) - Media requests for Jellyfin/Emby/Plex
-- **Ombi**: [github.com/Ombi-app/Ombi](https://github.com/Ombi-app/Ombi) - Media request platform
-- **Jellystat**: [github.com/CyferShepard/Jellystat](https://github.com/CyferShepard/Jellystat) - Jellyfin statistics
-
-#### 🔒 Network & Security
-- **Traefik**: [github.com/traefik/traefik](https://github.com/traefik/traefik) - Modern reverse proxy
-- **Nginx Proxy Manager**: [github.com/NginxProxyManager/nginx-proxy-manager](https://github.com/NginxProxyManager/nginx-proxy-manager) - Nginx proxy management
-- **Authelia**: [github.com/authelia/authelia](https://github.com/authelia/authelia) - Authentication & SSO
-
-#### 📈 Monitoring & Management
-- **Portainer**: [github.com/portainer/portainer](https://github.com/portainer/portainer) - Container management
-- **Watchtower**: [github.com/containrrr/watchtower](https://github.com/containrrr/watchtower) - Automatic updates
-- **Uptime Kuma**: [github.com/louislam/uptime-kuma](https://github.com/louislam/uptime-kuma) - Uptime monitoring
-
-### When to Contact HOPS vs Service Developers
-
-**Contact HOPS** for:
-- Installation/deployment issues
-- Docker Compose generation problems  
-- Cross-platform compatibility issues
-- Script errors or automation failures
-
-**Contact Service Developers** for:
-- Service configuration help
-- Feature requests for individual services
-- Bugs within the service itself
-- Service-specific documentation
+MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
 **Made with ❤️ for the homelab community**
-
-*HOPS - Making homelab deployment simple, secure, and reliable.*

SERVICES.md

@@ -0,0 +1,300 @@
+# Supported Services
+
+HOPS supports a comprehensive collection of homelab services across multiple categories. All services use LinuxServer.io containers for consistency and reliability.
+
+## 📺 Media Management (*arr Stack)
+
+### Sonarr - TV Series Management
+**Purpose**: Automatic TV show downloading and management  
+**Default Port**: 8989  
+**Support**: [github.com/Sonarr/Sonarr](https://github.com/Sonarr/Sonarr)  
+**Documentation**: [wiki.servarr.com/sonarr](https://wiki.servarr.com/sonarr)
+
+### Radarr - Movie Management
+**Purpose**: Automatic movie downloading and management  
+**Default Port**: 7878  
+**Support**: [github.com/Radarr/Radarr](https://github.com/Radarr/Radarr)  
+**Documentation**: [wiki.servarr.com/radarr](https://wiki.servarr.com/radarr)
+
+### Lidarr - Music Management
+**Purpose**: Automatic music downloading and management  
+**Default Port**: 8686  
+**Support**: [github.com/Lidarr/Lidarr](https://github.com/Lidarr/Lidarr)  
+**Documentation**: [wiki.servarr.com/lidarr](https://wiki.servarr.com/lidarr)
+
+### Readarr - eBook Management
+**Purpose**: Automatic eBook and audiobook downloading  
+**Default Port**: 8787  
+**Support**: [github.com/Readarr/Readarr](https://github.com/Readarr/Readarr)  
+**Documentation**: [wiki.servarr.com/readarr](https://wiki.servarr.com/readarr)  
+**Status**: ⚠️ Project retired, limited support
+
+### Bazarr - Subtitle Management
+**Purpose**: Automatic subtitle downloading for movies and TV  
+**Default Port**: 6767  
+**Support**: [github.com/morpheus65535/bazarr](https://github.com/morpheus65535/bazarr)  
+**Documentation**: [wiki.bazarr.media](https://wiki.bazarr.media)
+
+### Prowlarr - Indexer Management
+**Purpose**: Centralized indexer management for *arr applications  
+**Default Port**: 9696  
+**Support**: [github.com/Prowlarr/Prowlarr](https://github.com/Prowlarr/Prowlarr)  
+**Documentation**: [wiki.servarr.com/prowlarr](https://wiki.servarr.com/prowlarr)
+
+### Tdarr - Media Transcoding
+**Purpose**: Automated media transcoding and health checking  
+**Default Port**: 8265  
+**Support**: [github.com/HaveAGitGat/Tdarr](https://github.com/HaveAGitGat/Tdarr)  
+**Documentation**: [docs.tdarr.io](https://docs.tdarr.io)
+
+### Huntarr - Missing Media Discovery
+**Purpose**: Automated discovery and addition of missing media  
+**Default Port**: 7879  
+**Support**: [github.com/plexguide/Huntarr.io](https://github.com/plexguide/Huntarr.io)  
+**Documentation**: Community-driven
+
+## ⬇️ Download Clients
+
+### qBittorrent - BitTorrent Client
+**Purpose**: Feature-rich BitTorrent client with web interface  
+**Default Port**: 8080  
+**Support**: [github.com/qbittorrent/qBittorrent](https://github.com/qbittorrent/qBittorrent)  
+**Documentation**: [github.com/qbittorrent/qBittorrent/wiki](https://github.com/qbittorrent/qBittorrent/wiki)
+
+### Transmission - Lightweight BitTorrent
+**Purpose**: Simple, lightweight BitTorrent client  
+**Default Port**: 9091  
+**Support**: [github.com/transmission/transmission](https://github.com/transmission/transmission)  
+**Documentation**: [transmissionbt.com](https://transmissionbt.com)
+
+### NZBGet - Usenet Downloader
+**Purpose**: Efficient Usenet binary newsreader  
+**Default Port**: 6789  
+**Support**: [github.com/nzbget/nzbget](https://github.com/nzbget/nzbget)  
+**Documentation**: [nzbget.net/documentation](https://nzbget.net/documentation)
+
+### SABnzbd - Usenet Client
+**Purpose**: Popular web-based Usenet client  
+**Default Port**: 8081  
+**Support**: [github.com/sabnzbd/sabnzbd](https://github.com/sabnzbd/sabnzbd)  
+**Documentation**: [sabnzbd.org/wiki](https://sabnzbd.org/wiki)
+
+## 🎞️ Media Servers
+
+### Jellyfin - Open Source Media Server
+**Purpose**: Free, open-source media server and entertainment hub  
+**Default Port**: 8096  
+**Support**: [github.com/jellyfin/jellyfin](https://github.com/jellyfin/jellyfin)  
+**Documentation**: [jellyfin.org/docs](https://jellyfin.org/docs)  
+**Features**: No licensing fees, privacy-focused, extensive format support
+
+### Plex - Media Server Platform
+**Purpose**: Popular media server with premium features  
+**Default Port**: 32400  
+**Support**: [github.com/plexinc/pms-docker](https://github.com/plexinc/pms-docker)  
+**Documentation**: [support.plex.tv](https://support.plex.tv)  
+**Features**: Remote access, premium features with Plex Pass
+
+### Emby - Personal Media Server
+**Purpose**: Feature-rich personal media server  
+**Default Port**: 8097  
+**Support**: [github.com/MediaBrowser/Emby](https://github.com/MediaBrowser/Emby)  
+**Documentation**: [emby.media/support](https://emby.media/support)  
+**Features**: Premium features available, family-friendly
+
+### Jellystat - Jellyfin Statistics
+**Purpose**: Advanced statistics and monitoring for Jellyfin  
+**Default Port**: 3000  
+**Support**: [github.com/CyferShepard/Jellystat](https://github.com/CyferShepard/Jellystat)  
+**Documentation**: GitHub repository  
+**Requirements**: Requires Jellyfin server
+
+## 🎛️ Request Management
+
+### Overseerr - Plex Request Management
+**Purpose**: Media discovery and request management for Plex  
+**Default Port**: 5055  
+**Support**: [github.com/sct/overseerr](https://github.com/sct/overseerr)  
+**Documentation**: [docs.overseerr.dev](https://docs.overseerr.dev)  
+**Integration**: Plex, Sonarr, Radarr
+
+### Jellyseerr - Jellyfin Request Management
+**Purpose**: Media requests for Jellyfin, Emby, and Plex  
+**Default Port**: 5056  
+**Support**: [github.com/fallenbagel/jellyseerr](https://github.com/fallenbagel/jellyseerr)  
+**Documentation**: [docs.jellyseerr.dev](https://docs.jellyseerr.dev)  
+**Integration**: Jellyfin, Emby, Plex, Sonarr, Radarr
+
+### Ombi - Media Request Platform
+**Purpose**: User-friendly media request and discovery platform  
+**Default Port**: 3579  
+**Support**: [github.com/Ombi-app/Ombi](https://github.com/Ombi-app/Ombi)  
+**Documentation**: [docs.ombi.app](https://docs.ombi.app)  
+**Integration**: Plex, Emby, Jellyfin
+
+## 🔒 Reverse Proxy & Security
+
+### Traefik - Modern Reverse Proxy
+**Purpose**: Automatic reverse proxy with SSL certificate management  
+**Default Ports**: 80, 443, 8080 (dashboard)  
+**Support**: [github.com/traefik/traefik](https://github.com/traefik/traefik)  
+**Documentation**: [doc.traefik.io/traefik](https://doc.traefik.io/traefik)  
+**Features**: Automatic SSL, service discovery, load balancing
+
+### Nginx Proxy Manager - Easy Reverse Proxy
+**Purpose**: User-friendly web interface for Nginx reverse proxy  
+**Default Ports**: 80, 443, 81 (admin)  
+**Support**: [github.com/NginxProxyManager/nginx-proxy-manager](https://github.com/NginxProxyManager/nginx-proxy-manager)  
+**Documentation**: [nginxproxymanager.com/guide](https://nginxproxymanager.com/guide)  
+**Features**: Web GUI, SSL automation, access lists
+
+### Caddy - Automatic HTTPS Web Server
+**Purpose**: Modern web server with automatic HTTPS  
+**Default Ports**: 80, 443, 2019 (admin)  
+**Support**: [github.com/caddyserver/caddy](https://github.com/caddyserver/caddy)  
+**Documentation**: [caddyserver.com/docs](https://caddyserver.com/docs)  
+**Note**: ⚠️ **Configuration not included** - Users must provide their own Caddyfile
+
+### Authelia - Authentication & Authorization
+**Purpose**: Multi-factor authentication and single sign-on  
+**Default Port**: 9091  
+**Support**: [github.com/authelia/authelia](https://github.com/authelia/authelia)  
+**Documentation**: [authelia.com/integration](https://www.authelia.com/integration)  
+**Features**: 2FA, LDAP, OAuth2, OIDC
+
+## 📈 Monitoring & Management
+
+### Portainer - Container Management
+**Purpose**: Web-based Docker container management interface  
+**Default Port**: 9000  
+**Support**: [github.com/portainer/portainer](https://github.com/portainer/portainer)  
+**Documentation**: [docs.portainer.io](https://docs.portainer.io)  
+**Features**: Container management, stack deployment, monitoring
+
+### Uptime Kuma - Service Monitoring
+**Purpose**: Self-hosted uptime monitoring tool  
+**Default Port**: 3001  
+**Support**: [github.com/louislam/uptime-kuma](https://github.com/louislam/uptime-kuma)  
+**Documentation**: [github.com/louislam/uptime-kuma/wiki](https://github.com/louislam/uptime-kuma/wiki)  
+**Features**: Multiple protocols, notifications, status pages
+
+### Watchtower - Automatic Updates
+**Purpose**: Automatic Docker container updating  
+**Default Port**: None (background service)  
+**Support**: [github.com/containrrr/watchtower](https://github.com/containrrr/watchtower)  
+**Documentation**: [containrrr.dev/watchtower](https://containrrr.dev/watchtower)  
+**Features**: Scheduled updates, notifications, selective updating
+
+## 🔧 Service Dependencies
+
+### Common Dependencies
+Most services depend on:
+- **Docker** and **Docker Compose**
+- **Shared network** (`homelab` network)
+- **Volume mounts** for configuration and data
+- **Environment variables** (PUID, PGID, TZ)
+
+### Integration Patterns
+
+#### Media Management Workflow
+1. **Prowlarr** → Manages indexers for all *arr services
+2. **Sonarr/Radarr** → Monitors for new releases
+3. **Download Client** (qBittorrent/Transmission) → Downloads content
+4. **Media Server** (Jellyfin/Plex) → Serves content to users
+5. **Request System** (Overseerr/Jellyseerr) → User requests interface
+
+#### Security & Access
+1. **Reverse Proxy** (Traefik/Nginx) → External access with SSL
+2. **Authelia** → Authentication layer
+3. **Firewall** → Network security (UFW on Linux)
+
+#### Monitoring Stack
+1. **Portainer** → Container management
+2. **Uptime Kuma** → Service monitoring
+3. **Watchtower** → Automatic updates
+
+## ⚠️ Important Service Notes
+
+### Caddy Configuration
+HOPS provides the Caddy container but **does not include Caddyfile configuration**. Users must:
+1. Create their own Caddyfile in `~/hops/config/caddy/`
+2. Configure reverse proxy rules
+3. Set up SSL certificates (automatic with proper domain configuration)
+
+**Example minimal Caddyfile:**
+```
+example.com {
+    reverse_proxy jellyfin:8096
+}
+
+radarr.example.com {
+    reverse_proxy radarr:7878
+}
+```
+
+### GPU Support
+- **Linux**: Intel GPU support via `/dev/dri` passthrough
+- **macOS**: No GPU acceleration available
+- **Windows**: Limited GPU support in WSL2
+
+### Service Health Checks
+All web-based services include health checks for:
+- Service startup verification
+- Automatic restart on failure
+- Status monitoring integration
+
+## 🆘 Service-Specific Support
+
+### When to Contact Service Developers
+
+**Contact individual service developers for:**
+- Service configuration help
+- Feature requests
+- Bugs within the service itself
+- Service-specific documentation
+- Advanced service setup
+
+**Contact HOPS for:**
+- Docker Compose generation issues
+- Service deployment problems
+- Cross-platform compatibility
+- Installation and automation issues
+
+### Getting Service Help
+
+1. **Check service documentation** (links provided above)
+2. **Review service GitHub issues** for known problems
+3. **Check service community forums** (Reddit, Discord, etc.)
+4. **Consult LinuxServer.io documentation** for container-specific issues
+5. **Submit issues to appropriate repositories** with proper logs and details
+
+### Common Service Issues
+
+#### Permission Problems
+```bash
+# Fix ownership for Linux
+sudo chown -R $USER:$USER /opt/appdata/[service-name]
+
+# Fix ownership for macOS
+sudo chown -R $USER:$USER ~/hops/config/[service-name]
+```
+
+#### Service Won't Start
+```bash
+# Check service logs
+docker compose logs [service-name]
+
+# Restart service
+docker compose restart [service-name]
+```
+
+#### Configuration Issues
+Most services store configuration in:
+- **Linux**: `/opt/appdata/[service-name]/`
+- **macOS**: `~/hops/config/[service-name]/`
+- **Windows**: `/opt/appdata/[service-name]/` (in WSL2)
+
+---
+
+For installation help, see [INSTALLATION.md](INSTALLATION.md).  
+For advanced configuration, see [ADVANCED.md](ADVANCED.md).

TROUBLESHOOTING.md

@@ -0,0 +1,314 @@
+# HOPS Troubleshooting Guide
+
+This document provides solutions to common issues encountered when installing and running HOPS.
+
+## 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
+   ```
+
+2. **Fix missing Docker group:**
+   ```bash
+   sudo groupadd docker
+   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:**
+   ```bash
+   sudo chown -R $USER:$USER ~/hops
+   sudo chmod -R 755 ~/hops
+   ```
+
+## Service Access Issues
+
+### 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
+   sudo docker compose logs [service-name]
+   ```
+
+2. **Verify port availability:**
+   ```bash
+   sudo netstat -tlnp | grep :8989  # For Sonarr
+   sudo ss -tlnp | grep :8989       # Alternative command
+   ```
+
+3. **Check firewall settings:**
+   ```bash
+   sudo ufw status
+   # If needed, allow ports:
+   sudo ufw allow 8989  # Example for Sonarr
+   ```
+
+4. **Restart services:**
+   ```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
+   sudo docker network rm traefik homelab
+   ```
+
+3. **Recreate networks:**
+   ```bash
+   cd ~/hops
+   sudo docker compose up -d
+   ```
+
+## System Requirements
+
+### Insufficient Resources
+
+**Symptoms:**
+- 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
+
+# Container status
+cd ~/hops && sudo docker compose ps
+```
+
+### Reporting 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
+```

discord-header.md

@@ -0,0 +1,5 @@
+# HOPS Discord Channel Header
+
+**HOPS - Homelab Orchestration Provisioning Script** 🏠  
+Cross-platform automation tool for deploying homelab infrastructure using Docker Compose. Menu-driven installation and management of media servers, download clients, monitoring tools, and more. Supports Linux, macOS, and Windows (WSL2).  
+🔗 **GitHub**: https://github.com/skiercm/hops

hops

@@ -2,13 +2,13 @@
 
 # HOPS - Homelab Orchestration Provisioning Script
 # Primary Management Script
-# Version: 3.2.0
+# Version: 3.3.0
 
 # Exit on any error
 set -e
 
 # Script version and metadata
-readonly SCRIPT_VERSION="3.2.0"
+readonly SCRIPT_VERSION="3.3.0"
 readonly SCRIPT_NAME="HOPS"
 readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -17,19 +17,11 @@ readonly INSTALLER_SCRIPT="$SCRIPT_DIR/install"
 readonly UNINSTALLER_SCRIPT="$SCRIPT_DIR/uninstall"
 readonly SERVICE_DEFINITIONS="$SCRIPT_DIR/services"
 
-# Color codes for output
-readonly RED='\033[0;31m'
-readonly GREEN='\033[0;32m'
-readonly YELLOW='\033[1;33m'
-readonly BLUE='\033[0;34m'
-readonly PURPLE='\033[0;35m'
-readonly CYAN='\033[0;36m'
-readonly WHITE='\033[1;37m'
-readonly NC='\033[0m' # No Color
-
 # Load system utilities
 source "$SCRIPT_DIR/lib/system.sh"
 
+# Color codes are defined in lib/common.sh
+
 # Logging setup (will be set by setup_logging)
 LOG_DIR=""
 LOG_FILE=""
@@ -546,6 +538,109 @@ show_logs() {
     read -r
 }
 
+# Check for updates
+check_for_updates() {
+    info "Checking for updates..."
+    
+    # Check if we're in a git repository
+    if ! git -C "$SCRIPT_DIR" rev-parse --git-dir >/dev/null 2>&1; then
+        warning "Not in a git repository. Cannot check for updates."
+        return 1
+    fi
+    
+    # Fetch latest changes
+    if ! git -C "$SCRIPT_DIR" fetch origin main >/dev/null 2>&1; then
+        warning "Failed to fetch updates from remote repository."
+        return 1
+    fi
+    
+    # Check if we're behind
+    local local_commit=$(git -C "$SCRIPT_DIR" rev-parse HEAD)
+    local remote_commit=$(git -C "$SCRIPT_DIR" rev-parse origin/main)
+    
+    if [[ "$local_commit" == "$remote_commit" ]]; then
+        success "HOPS is up to date (v$SCRIPT_VERSION)"
+        return 0
+    else
+        local commits_behind=$(git -C "$SCRIPT_DIR" rev-list --count HEAD..origin/main)
+        warning "HOPS is $commits_behind commits behind. Update available!"
+        
+        # Show what's new
+        echo -e "\n${BLUE}📋 Recent changes:${NC}"
+        git -C "$SCRIPT_DIR" log --oneline --max-count=5 HEAD..origin/main | sed 's/^/   • /'
+        return 1
+    fi
+}
+
+# Update HOPS
+update_hops() {
+    show_header
+    echo -e "${WHITE}🔄 HOPS Update${NC}\n"
+    
+    # Check if we're in a git repository
+    if ! git -C "$SCRIPT_DIR" rev-parse --git-dir >/dev/null 2>&1; then
+        error_exit "Not in a git repository. Cannot update automatically."
+    fi
+    
+    # Check for local changes
+    if ! git -C "$SCRIPT_DIR" diff-index --quiet HEAD --; then
+        warning "Local changes detected. These will be backed up before updating."
+        
+        # Create backup
+        local backup_dir="$SCRIPT_DIR/.backup-$(date +%Y%m%d-%H%M%S)"
+        info "Creating backup at: $backup_dir"
+        
+        if ! cp -r "$SCRIPT_DIR" "$backup_dir"; then
+            error_exit "Failed to create backup"
+        fi
+        
+        success "Backup created successfully"
+    fi
+    
+    # Fetch and show what will be updated
+    info "Fetching latest changes..."
+    if ! git -C "$SCRIPT_DIR" fetch origin main; then
+        error_exit "Failed to fetch updates from remote repository"
+    fi
+    
+    # Check if update is needed
+    if ! check_for_updates; then
+        echo -e "\n${WHITE}Continue with update? [y/N]: ${NC}"
+        read -r update_choice
+        if [[ ! "$update_choice" =~ ^[Yy]$ ]]; then
+            info "Update cancelled"
+            echo -e "\n${WHITE}Press Enter to return to main menu...${NC}"
+            read -r
+            return
+        fi
+    else
+        info "Already up to date"
+        echo -e "\n${WHITE}Press Enter to return to main menu...${NC}"
+        read -r
+        return
+    fi
+    
+    # Perform the update
+    info "Updating HOPS..."
+    if git -C "$SCRIPT_DIR" pull origin main; then
+        success "HOPS updated successfully!"
+        
+        # Source the updated script to get new version
+        if [[ -f "$SCRIPT_DIR/hops" ]]; then
+            local new_version=$(grep '^readonly SCRIPT_VERSION=' "$SCRIPT_DIR/hops" | cut -d'"' -f2)
+            success "Updated to version $new_version"
+        fi
+        
+        echo -e "\n${YELLOW}💡 Note: Please restart HOPS to use the updated version${NC}"
+    else
+        error_exit "Update failed. Your installation may be in an inconsistent state."
+    fi
+    
+    echo -e "\n${WHITE}Press Enter to exit (restart HOPS to use new version)...${NC}"
+    read -r
+    exit 0
+}
+
 # Show help information
 show_help() {
     show_header
@@ -624,11 +719,12 @@ show_main_menu() {
         echo -e "  5) Access Information ${YELLOW}(not installed)${NC}"
     fi
     
-    echo -e "  6) View Logs"
-    echo -e "  7) Help & Documentation"
-    echo -e "  8) Exit"
+    echo -e "  6) Check for Updates"
+    echo -e "  7) View Logs"
+    echo -e "  8) Help & Documentation"
+    echo -e "  9) Exit"
     
-    echo -e "\n${WHITE}Select an option [1-8]: ${NC}"
+    echo -e "\n${WHITE}Select an option [1-9]: ${NC}"
 }
 
 # Main program loop
@@ -662,24 +758,87 @@ main() {
                 show_access_info
                 ;;
             6)
-                show_logs
+                # Check for updates and optionally update
+                if check_for_updates; then
+                    echo -e "\n${WHITE}Press Enter to return to main menu...${NC}"
+                    read -r
+                else
+                    echo -e "\n${WHITE}Would you like to update now? [y/N]: ${NC}"
+                    read -r update_choice
+                    if [[ "$update_choice" =~ ^[Yy]$ ]]; then
+                        update_hops
+                    fi
+                fi
                 ;;
             7)
-                show_help
+                show_logs
                 ;;
             8)
+                show_help
+                ;;
+            9)
                 info "Thank you for using HOPS!"
                 exit 0
                 ;;
             *)
-                warning "Invalid option. Please select 1-8."
+                warning "Invalid option. Please select 1-9."
                 sleep 2
                 ;;
         esac
     done
 }
 
+# Handle command line arguments
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --update)
+                init_logging
+                check_root
+                update_hops
+                exit $?
+                ;;
+            --check-updates)
+                init_logging
+                if check_for_updates; then
+                    exit 0
+                else
+                    exit 1
+                fi
+                ;;
+            --version)
+                echo "HOPS v$SCRIPT_VERSION"
+                exit 0
+                ;;
+            --help|-h)
+                echo "HOPS - Homelab Orchestration Provisioning Script v$SCRIPT_VERSION"
+                echo ""
+                echo "Usage: $0 [options]"
+                echo ""
+                echo "Options:"
+                echo "  --update         Update HOPS to the latest version"
+                echo "  --check-updates  Check if updates are available (exit 1 if updates available)"
+                echo "  --version        Show version information"
+                echo "  --help, -h       Show this help message"
+                echo ""
+                echo "When run without options, HOPS starts in interactive mode."
+                exit 0
+                ;;
+            *)
+                echo "Unknown option: $1"
+                echo "Use --help for usage information."
+                exit 1
+                ;;
+        esac
+        shift
+    done
+}
+
 # Script entry point
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
+    # Parse command line arguments first
+    parse_args "$@"
+    
+    # If no arguments provided, run main interactive mode
+    main
 fi

install

@@ -665,7 +665,13 @@ EOF
         log "🚀 Starting deployment..."
 
         # Ensure we're in the correct directory
-        local HOMELAB_DIR="$HOME/hops"
+        # When running with sudo, use the original user's home directory
+        local HOMELAB_DIR
+        if [[ -n "$SUDO_USER" ]]; then
+            HOMELAB_DIR="$(eval echo ~$SUDO_USER)/hops"
+        else
+            HOMELAB_DIR="$HOME/hops"
+        fi
         if [[ ! -d "$HOMELAB_DIR" ]]; then
             error_exit_with_rollback "Homelab directory not found: $HOMELAB_DIR"
         fi

lib/privileges.sh

@@ -196,8 +196,36 @@ install_docker() {
     # Add Docker GPG key
     curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
     
-    # Add Docker repository
-    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+    # Add Docker repository with proper Ubuntu codename detection for Linux Mint
+    local ubuntu_codename
+    if [[ "$(lsb_release -is)" == "Linuxmint" ]]; then
+        # Linux Mint provides UBUNTU_CODENAME in /etc/os-release
+        if [[ -f /etc/os-release ]]; then
+            ubuntu_codename=$(grep '^UBUNTU_CODENAME=' /etc/os-release | cut -d= -f2)
+        fi
+        
+        # Fallback to version mapping if UBUNTU_CODENAME not found
+        if [[ -z "$ubuntu_codename" ]]; then
+            case "$(lsb_release -rs)" in
+                "22"|"22.1"|"22.2"|"22.3")
+                    ubuntu_codename="noble"  # Ubuntu 24.04
+                    ;;
+                "21"|"21.1"|"21.2"|"21.3")
+                    ubuntu_codename="jammy"  # Ubuntu 22.04
+                    ;;
+                "20"|"20.1"|"20.2"|"20.3")
+                    ubuntu_codename="focal"  # Ubuntu 20.04
+                    ;;
+                *)
+                    ubuntu_codename="noble"  # Default to latest LTS
+                    ;;
+            esac
+        fi
+    else
+        ubuntu_codename=$(lsb_release -cs)
+    fi
+    
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $ubuntu_codename stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
     
     # Update package index with Docker packages
     apt-get update

lib/system.sh

@@ -602,6 +602,7 @@ get_primary_ip() {
 
 # Remove existing Docker installation on Linux
 remove_docker_linux() {
+    echo "DEBUG: remove_docker_linux() function called"
     info "🗑️ Removing existing Docker installation..."
     
     # Stop Docker service if running
@@ -622,6 +623,23 @@ remove_docker_linux() {
         systemctl disable docker
     fi
     
+    # Remove Docker repository and GPG keys FIRST to prevent apt errors
+    info "🗑️ Removing Docker repository and keys..."
+    rm -f /etc/apt/sources.list.d/docker.list
+    rm -f /etc/apt/sources.list.d/*docker*
+    rm -f /etc/apt/keyrings/docker.gpg
+    rm -f /usr/share/keyrings/docker*
+    rm -f /etc/apt/keyrings/docker*
+    
+    # Also check for and remove any repositories that might contain Linux Mint codenames
+    if grep -r "download.docker.com.*xia\|download.docker.com.*vera\|download.docker.com.*vanessa" /etc/apt/sources.list.d/ 2>/dev/null; then
+        info "🗑️ Found Docker repositories with Linux Mint codenames, removing..."
+        grep -l "download.docker.com.*xia\|download.docker.com.*vera\|download.docker.com.*vanessa" /etc/apt/sources.list.d/* 2>/dev/null | xargs rm -f
+    fi
+    
+    # Clean apt cache to remove any cached repository data
+    apt-get clean
+    
     # Remove Docker packages
     info "🗑️ Removing Docker packages..."
     apt-get remove -y docker docker-engine docker.io containerd runc docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin 2>/dev/null || true
@@ -657,16 +675,7 @@ remove_docker_linux() {
         groupdel docker 2>/dev/null || true
     fi
     
-    # Remove Docker repository
-    if [[ -f "/etc/apt/sources.list.d/docker.list" ]]; then
-        info "🗑️ Removing Docker repository..."
-        rm -f "/etc/apt/sources.list.d/docker.list"
-    fi
-    
-    # Remove Docker GPG key
-    if [[ -f "/etc/apt/keyrings/docker.gpg" ]]; then
-        rm -f "/etc/apt/keyrings/docker.gpg"
-    fi
+    # Repository and GPG keys already removed above
     
     # Remove any remaining Docker processes
     pkill -f docker 2>/dev/null || true
@@ -811,6 +820,7 @@ check_existing_docker_macos() {
 
 # Install Docker for the current platform
 install_docker() {
+    echo "DEBUG: install_docker() function called from lib/system.sh"
     info "🐳 Installing Docker..."
     
     case "$OS_NAME_LOWER" in
@@ -1030,8 +1040,10 @@ install_docker() {
             fi
             ;;
         "ubuntu"|"debian"|"linuxmint"|"mint")
+            echo "DEBUG: Linux/Ubuntu/Mint Docker installation path"
             # Check for existing Docker installation
             if command_exists docker; then
+                echo "DEBUG: Existing Docker installation detected"
                 local docker_version=$(docker --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)
                 
                 warning "Existing Docker installation detected:"
@@ -1069,10 +1081,13 @@ install_docker() {
                     fi
                     
                     success "Existing Docker installation is compatible"
+                    echo "DEBUG: Returning early - skipping Linux Mint repository fix"
                     return 0
                 fi
             fi
             
+            echo "DEBUG: No existing Docker found, proceeding with fresh installation"
+            
             # Check for and handle conflicting files
             local conflicting_files=()
             local potential_conflicts=(
@@ -1119,9 +1134,57 @@ install_docker() {
                 fi
             fi
             
-            # Install fresh Docker using the official script
+            # Install fresh Docker using manual repository setup
             info "📦 Installing Docker Engine..."
-            curl -fsSL https://get.docker.com | sh
+            
+            # Install required packages
+            apt-get update
+            apt-get install -y ca-certificates curl gnupg lsb-release
+            
+            # Add Docker GPG key
+            curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+            
+            # Add Docker repository with proper Ubuntu codename detection for Linux Mint
+            local ubuntu_codename
+            echo "DEBUG: Configuring Docker repository"
+            echo "DEBUG: Detected OS: $(lsb_release -is)"
+            if [[ "$(lsb_release -is)" == "Linuxmint" ]]; then
+                echo "DEBUG: Linux Mint detected, checking for UBUNTU_CODENAME"
+                # Linux Mint provides UBUNTU_CODENAME in /etc/os-release
+                if [[ -f /etc/os-release ]]; then
+                    ubuntu_codename=$(grep '^UBUNTU_CODENAME=' /etc/os-release | cut -d= -f2)
+                    echo "DEBUG: Found UBUNTU_CODENAME=$ubuntu_codename in /etc/os-release"
+                fi
+                
+                # Fallback to version mapping if UBUNTU_CODENAME not found
+                if [[ -z "$ubuntu_codename" ]]; then
+                    case "$(lsb_release -rs)" in
+                        "22"|"22.1"|"22.2"|"22.3")
+                            ubuntu_codename="noble"  # Ubuntu 24.04
+                            ;;
+                        "21"|"21.1"|"21.2"|"21.3")
+                            ubuntu_codename="jammy"  # Ubuntu 22.04
+                            ;;
+                        "20"|"20.1"|"20.2"|"20.3")
+                            ubuntu_codename="focal"  # Ubuntu 20.04
+                            ;;
+                        *)
+                            ubuntu_codename="noble"  # Default to latest LTS
+                            ;;
+                    esac
+                fi
+            else
+                ubuntu_codename=$(lsb_release -cs)
+            fi
+            
+            info "Using Ubuntu codename: $ubuntu_codename for Docker repository"
+            echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $ubuntu_codename stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+            
+            # Update package index with Docker packages
+            apt-get update
+            
+            # Install Docker
+            apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
             
             # Add user to docker group if we're running with sudo
             if [[ -n "$SUDO_USER" ]]; then

privileged-setup

@@ -40,8 +40,37 @@ install_docker() {
     # Add Docker GPG key
     curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
     
-    # Add Docker repository
-    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+    # Add Docker repository with proper Ubuntu codename detection for Linux Mint
+    local ubuntu_codename
+    if [[ "$(lsb_release -is)" == "Linuxmint" ]]; then
+        # Linux Mint provides UBUNTU_CODENAME in /etc/os-release
+        if [[ -f /etc/os-release ]]; then
+            ubuntu_codename=$(grep '^UBUNTU_CODENAME=' /etc/os-release | cut -d= -f2)
+        fi
+        
+        # Fallback to version mapping if UBUNTU_CODENAME not found
+        if [[ -z "$ubuntu_codename" ]]; then
+            case "$(lsb_release -rs)" in
+                "22"|"22.1"|"22.2"|"22.3")
+                    ubuntu_codename="noble"  # Ubuntu 24.04
+                    ;;
+                "21"|"21.1"|"21.2"|"21.3")
+                    ubuntu_codename="jammy"  # Ubuntu 22.04
+                    ;;
+                "20"|"20.1"|"20.2"|"20.3")
+                    ubuntu_codename="focal"  # Ubuntu 20.04
+                    ;;
+                *)
+                    ubuntu_codename="noble"  # Default to latest LTS
+                    ;;
+            esac
+        fi
+    else
+        ubuntu_codename=$(lsb_release -cs)
+    fi
+    
+    echo "DEBUG: Detected OS: $(lsb_release -is), Ubuntu codename: $ubuntu_codename"
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $ubuntu_codename stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
     
     # Update package index with Docker packages
     apt-get update

summary7-19.txt

@@ -0,0 +1,170 @@
+# HOPS Linux Mint Docker Repository Troubleshooting Summary
+## Date: July 19, 2025
+
+### Problem Description
+HOPS installation failing on Linux Mint 22.1 with Docker repository error:
+```
+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 Analysis
+- Linux Mint uses its own codenames (e.g., "xia" for version 22.1)
+- Docker repositories are structured around Ubuntu codenames (e.g., "noble", "jammy", "focal")
+- HOPS was using `lsb_release -cs` which returns "xia" instead of the Ubuntu base codename
+- Docker doesn't have a repository for Linux Mint's "xia" codename
+
+### System Information (Linux Mint 22.1)
+```
+Distributor ID: LinuxMint
+Description: Linux Mint 22.1
+Release: 22.1
+Codename: xia
+UBUNTU_CODENAME=noble (from /etc/os-release)
+```
+
+### Troubleshooting Steps Attempted
+
+#### 1. Initial Fix Attempt (Commit af57a77)
+**Files Modified:** `privileged-setup`, `lib/privileges.sh`
+**Approach:** Added Linux Mint version to Ubuntu codename mapping
+- Mint 22.x → Ubuntu 24.04 (noble)
+- Mint 21.x → Ubuntu 22.04 (jammy)
+- Mint 20.x → Ubuntu 20.04 (focal)
+
+**Result:** Still failed with same error
+
+#### 2. System Cleanup
+**Commands Executed:**
+```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 grep -i docker /etc/apt/sources.list
+sudo apt clean
+sudo apt autoclean
+```
+
+**Result:** Confirmed clean state, but error persisted
+
+#### 3. Improved Fix (Commit 4fd78ec)
+**Files Modified:** `privileged-setup`, `lib/privileges.sh`
+**Approach:** Use `UBUNTU_CODENAME` from `/etc/os-release` with fallback to version mapping
+```bash
+# Primary method: Read UBUNTU_CODENAME from /etc/os-release
+ubuntu_codename=$(grep '^UBUNTU_CODENAME=' /etc/os-release | cut -d= -f2)
+
+# Fallback: Version mapping if UBUNTU_CODENAME not found
+```
+
+**Result:** Still experiencing same error after system cleanup
+
+#### 4. Discovery of UBUNTU_CODENAME
+**Key Finding:** Linux Mint 22.1 provides `UBUNTU_CODENAME=noble` in `/etc/os-release`
+- This is the correct Ubuntu codename that Docker repositories support
+- Should eliminate need for manual version mapping
+
+#### 5. Root Cause Discovery - Wrong Installation Path (Session 2)
+**Date:** July 19, 2025 (Evening)
+**Discovery:** User was running `./setup` script, but fixes were applied to different code paths
+**Investigation Steps:**
+- Confirmed user had latest code with fixes (commit 4fd78ec)
+- System was completely clean of Docker repositories
+- `UBUNTU_CODENAME=noble` correctly detected
+- Still getting "xia" error despite fixes
+
+**Key Finding:** The `setup` script uses `lib/system.sh::install_docker()` which was calling Docker's convenience script `curl -fsSL https://get.docker.com | sh`, NOT the fixed installation functions in `privileged-setup` or `lib/privileges.sh`.
+
+#### 6. Fix Applied to Correct Installation Path (Commit ce0f7f2)
+**Files Modified:** `lib/system.sh` (lines 1122-1168)
+**Approach:** 
+- Replaced Docker convenience script with manual repository setup
+- Added Linux Mint Ubuntu codename detection logic to `lib/system.sh`
+- Included same UBUNTU_CODENAME detection and fallback mapping
+- Added debug output: "Using Ubuntu codename: X for Docker repository"
+
+**Result:** User tested after pulling latest code - still experiencing same "xia" error
+
+### Current Status (End of Session 2)
+**Problem State:** Persistent "xia" repository error despite comprehensive fixes
+**Fixes Applied:**
+- Three different installation paths updated with Linux Mint detection
+- Complete Docker repository cleanup performed multiple times
+- Debug output added to track codename detection
+- Manual testing confirmed UBUNTU_CODENAME=noble is available
+
+**Unresolved Questions:**
+1. Why debug output from fixed code is not appearing in installation logs
+2. Whether there's a fourth Docker installation path not yet discovered
+3. Possible system-level caching or existing Docker installation interfering
+4. Whether the correct script path is actually being executed
+
+### Next Steps (For Tomorrow)
+1. **Execution Path Verification:** Add debug traces to determine which exact functions are being called during `./setup`
+2. **Docker Installation Check:** Verify if Docker is already installed and causing early function returns
+3. **Complete Docker Removal:** If Docker exists, completely remove it before testing fixes
+4. **Alternative Installation Methods:** Test other entry points (`./hops`, `./install`, `./privileged-setup` directly)
+5. **System State Analysis:** Check for any persistent apt configurations or cached repository information
+
+### Technical Notes
+- Linux Mint consistently provides `UBUNTU_CODENAME` in modern versions
+- Using this field is more reliable than version-based mapping
+- Docker installation uses Ubuntu repositories for Debian-based distributions
+- Issue affects all Linux Mint installations using HOPS
+- The Docker convenience script `get.docker.com` has its own broken Linux Mint detection
+
+### Files Modified
+- `privileged-setup` (lines 43-70, 72) - ✅ Fixed
+- `lib/privileges.sh` (lines 199-226, 228) - ✅ Fixed  
+- `lib/system.sh` (lines 1122-1168) - ✅ Fixed
+
+#### 7. Final Resolution (Session 3 - July 20, 2025)
+**Root Cause Identified:** Critical case sensitivity bug in Linux Mint detection
+- `lsb_release -is` returns `"Linuxmint"` (lowercase 'm')
+- All code was checking for `"LinuxMint"` (uppercase 'M')
+- This caused Linux Mint detection to fail completely, falling back to "xia" codename
+
+**Final Fixes Applied:**
+1. **Case Sensitivity Fix (Commit 736ed1b):**
+   - Fixed `lib/system.sh:1151`: `"LinuxMint"` → `"Linuxmint"`
+   - Fixed `privileged-setup:45`: `"LinuxMint"` → `"Linuxmint"`  
+   - Fixed `lib/privileges.sh:201`: `"LinuxMint"` → `"Linuxmint"`
+
+2. **Debug Tracing Added (Commit d2e9a69):**
+   - Added comprehensive debug output to trace execution paths
+   - Fixed Docker repository cleanup order in `remove_docker_linux()`
+   - Added specific cleanup for Linux Mint codenames (xia, vera, vanessa)
+
+3. **Docker Service Issues (Manual Fix):**
+   - Created missing `docker` group: `sudo groupadd docker`
+   - Added user to docker group: `sudo usermod -aG docker skier`
+   - Started Docker services: `sudo systemctl start docker.socket docker`
+
+4. **Directory Detection Fix (Commit a28a6e5):**
+   - Fixed sudo home directory resolution in `install` script
+   - Changed `$HOME/hops` to use `$SUDO_USER` home directory
+   - Resolved `/root/hops` vs `/home/skier/hops` issue
+
+**Final Result:** ✅ **COMPLETE SUCCESS**
+- Docker repositories now use correct Ubuntu codename "noble"
+- Sonarr container deployed and running successfully
+- Web UI accessible at localhost:8989
+- All Linux Mint Docker repository issues resolved
+
+### Current Status (RESOLVED)
+**Problem State:** ✅ **COMPLETELY RESOLVED**
+**Final Working State:**
+- Linux Mint detection working: `DEBUG: Linux Mint detected, checking for UBUNTU_CODENAME`
+- Ubuntu codename detection: `DEBUG: Found UBUNTU_CODENAME=noble in /etc/os-release`
+- Repository configuration: `ℹ️ Using Ubuntu codename: noble for Docker repository`
+- Docker installation: Downloads from `https://download.docker.com/linux/ubuntu noble`
+- Service deployment: Sonarr running and accessible
+
+### Git Commits
+- `af57a77`: Initial Linux Mint version mapping fix
+- `4fd78ec`: Improved fix using UBUNTU_CODENAME detection  
+- `ce0f7f2`: Fix lib/system.sh Docker installation path with manual repository setup
+- `d2e9a69`: Fix Docker repository issues with debug tracing and cleanup order
+- `736ed1b`: Fix critical Linux Mint case sensitivity bug in repository detection
+- `a28a6e5`: Fix homelab directory detection when running with sudo