From a7213441dad84cb18a90c51ec946551b11c2c94a Mon Sep 17 00:00:00 2001 From: Stephen Klein Date: Wed, 10 Jun 2026 21:17:16 -0400 Subject: [PATCH] Stub out stale documentation, rebuild as Linux-only ADVANCED.md, INSTALLATION.md, and TROUBLESHOOTING.md were ~60-70% stale: references to deleted Path B scripts, macOS/WSL2 platform sections, old GitHub URLs, and v3.1-3.3 version history. Pruned to accurate Linux-only stubs to be rebuilt as the 1.0.0 codebase stabilises. Co-Authored-By: Claude Sonnet 4.6 --- ADVANCED.md | 713 ++------------------------------------------- INSTALLATION.md | 361 ++--------------------- TROUBLESHOOTING.md | 359 +++++------------------ 3 files changed, 130 insertions(+), 1303 deletions(-) diff --git a/ADVANCED.md b/ADVANCED.md index c1ee882..25a4e65 100644 --- a/ADVANCED.md +++ b/ADVANCED.md @@ -1,715 +1,64 @@ -# Advanced Configuration & Troubleshooting +# Advanced Configuration -This guide covers advanced HOPS configuration, troubleshooting, security features, and system administration. +This guide covers advanced HOPS configuration and system administration. -## 🔧 Advanced Configuration +> **Note**: This document is being rebuilt alongside the 1.0.0 codebase. +> Content will be expanded as features are stabilized. -### Environment Variables +## Environment Variables -HOPS uses both encrypted secret management and traditional environment files for configuration. +HOPS writes a `.env` file to `~/hops/` during installation. Key variables: -#### Encrypted Secret Management (v3.1.0+) ```bash -# Initialize secret management -./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 +PUID=1000 # User ID (run: id -u) +PGID=1000 # Group ID (run: id -g) TZ=America/New_York # Timezone -# Directory Configuration -DATA_ROOT=/mnt/media # Media storage (Linux) -CONFIG_ROOT=/opt/appdata # App configurations (Linux) +DATA_ROOT=/mnt/media # Media storage +CONFIG_ROOT=/opt/appdata # App configurations -# 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 +DEFAULT_ADMIN_PASSWORD=... # Auto-generated +DEFAULT_DB_PASSWORD=... # Auto-generated ``` -### Service-Specific Configuration +## Docker Compose Commands -#### Reverse Proxy Setup - -**Traefik Configuration:** -```bash -# Traefik automatically configured with labels -# Custom configuration in ~/hops/config/traefik/ - -# Example dynamic configuration -mkdir -p ~/hops/config/traefik/dynamic -cat > ~/hops/config/traefik/dynamic/middleware.yml << 'EOF' -http: - middlewares: - default-headers: - headers: - frameDeny: true - sslRedirect: true - browserXssFilter: true - contentTypeNosniff: true - forceSTSHeader: true - stsIncludeSubdomains: true - stsPreload: true - stsSeconds: 31536000 -EOF -``` - -**Nginx Proxy Manager:** -- Access admin interface on port 81 -- Default credentials: `admin@example.com` / `changeme` -- Configure SSL certificates through web interface - -**Caddy Configuration:** -```bash -# Create Caddy configuration directory -mkdir -p ~/hops/config/caddy - -# Create custom Caddyfile -cat > ~/hops/config/caddy/Caddyfile << 'EOF' -# Global options -{ - email your-email@domain.com - # Optional: Use custom CA - # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory -} - -# Main domain -yourdomain.com { - reverse_proxy jellyfin:8096 - - # Custom headers - header { - # Security headers - Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" - X-Content-Type-Options "nosniff" - X-Frame-Options "DENY" - Referrer-Policy "strict-origin-when-cross-origin" - } -} - -# Subdomain routing -sonarr.yourdomain.com { - reverse_proxy sonarr:8989 -} - -radarr.yourdomain.com { - reverse_proxy radarr:7878 -} - -# Internal services (authentication required) -portainer.yourdomain.com { - reverse_proxy portainer:9000 - - # Optional: IP allowlist - @internal { - remote_ip 192.168.1.0/24 10.0.0.0/8 - } - handle @internal { - reverse_proxy portainer:9000 - } - handle { - respond "Access denied" 403 - } -} -EOF -``` - -#### Authelia Integration -```bash -# Authelia configuration -mkdir -p ~/hops/config/authelia - -# Example configuration (simplified) -cat > ~/hops/config/authelia/configuration.yml << 'EOF' -theme: dark -default_redirection_url: https://yourdomain.com - -server: - host: 0.0.0.0 - port: 9091 - -log: - level: warn - -authentication_backend: - file: - path: /config/users_database.yml - password: - algorithm: argon2id - -access_control: - default_policy: deny - rules: - - domain: jellyfin.yourdomain.com - policy: bypass - - domain: "*.yourdomain.com" - policy: one_factor - -session: - name: authelia_session - domain: yourdomain.com - -regulation: - max_retries: 3 - ban_time: 10m - -storage: - local: - path: /config/db.sqlite3 - -notifier: - filesystem: - filename: /config/notification.txt -EOF -``` - -### Service Management Commands - -#### User Operations Script (No Sudo Required) -```bash -# Service status and control -./user-operations status # View all service status -./user-operations status jellyfin # View specific service -./user-operations logs jellyfin # View service logs -./user-operations logs jellyfin -f # Follow logs - -# Deployment operations -./user-operations deploy # Deploy all services -./user-operations stop # Stop all services -./user-operations restart # Restart all services -./user-operations restart jellyfin # Restart specific service - -# Update operations -./user-operations update # Update all containers -./user-operations update jellyfin # Update specific container -``` - -#### Direct Docker Compose Commands ```bash cd ~/hops -# Service management -docker compose ps # List services -docker compose up -d # Start all services -docker compose down # Stop all services -docker compose restart # Restart all services -docker compose restart 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 +docker compose ps # List services +docker compose up -d # Start all services +docker compose down # Stop all services +docker compose restart [service] # Restart a service +docker compose logs -f [service] # Follow logs +docker compose logs --tail=100 [service] # Last 100 lines +docker compose pull # Pull new images +docker compose up -d --force-recreate # Recreate containers +docker stats # Real-time resource usage +docker system df # Disk usage +docker system prune # Clean unused data ``` -### New Modular Architecture +## Firewall -HOPS v3.1.0+ introduces a modular library system: +HOPS configures UFW automatically on Linux. Manual management: -``` -hops/ -├── lib/ # Shared libraries -│ ├── common.sh # Logging, UI, utilities -│ ├── system.sh # OS detection, requirements -│ ├── docker.sh # Docker operations -│ ├── security.sh # Security functions -│ ├── validation.sh # Input validation -│ ├── secrets.sh # Secret management -│ └── privileges.sh # Privilege separation -├── setup # Main installation wrapper -├── privileged-setup # Root-only operations -├── user-operations # User operations -├── services-improved # Enhanced service definitions -└── hops # Main script -``` - -#### Using Library Functions ```bash -# Source libraries in custom scripts -source lib/common.sh -source lib/system.sh - -# Use logging functions -log "INFO" "Starting custom operation" -warning "This is a warning message" -error_exit "Fatal error occurred" - -# Use system functions -detect_os -check_system_requirements 2 10 # 2GB RAM, 10GB disk - -# Use validation functions -validate_port "8080" -validate_domain "example.com" -``` - -## 🔒 Security Features & Hardening - -### Automatic Security Hardening - -HOPS automatically implements several security measures: - -#### Firewall Configuration (Linux) -```bash -# UFW rules automatically created sudo ufw status - -# Manual firewall management sudo ufw allow 8096/tcp comment "Jellyfin" -sudo ufw allow 9000/tcp comment "Portainer" -sudo ufw delete allow 8096/tcp # Remove rule +sudo ufw delete allow 8096/tcp ``` -#### File Permissions -```bash -# Automatic permission hardening -# Secrets: 600 (owner read/write only) -# Configs: 644 (owner write, group/other read) -# Scripts: 755 (executable) +## File Permissions -# Manual permission fixes +```bash chmod 600 ~/hops/.env chmod 644 ~/hops/docker-compose.yml -chmod 755 ~/hops/user-operations -``` - -#### Network Isolation -```bash -# Docker network isolation -docker network ls | grep homelab -docker network inspect homelab - -# View network configuration -docker compose config | grep network -``` - -### Security Auditing -```bash -# Run security audit -./lib/security.sh audit - -# Check for security issues -./lib/security.sh check-passwords -./lib/security.sh check-permissions -./lib/security.sh check-firewall - -# Security recommendations -./lib/security.sh recommendations -``` - -### SSL/TLS Configuration - -#### Traefik SSL -Traefik automatically handles SSL certificates with Let's Encrypt: -```bash -# Check certificate status -docker compose logs traefik | grep -i certificate - -# Manual certificate renewal (if needed) -docker compose restart traefik -``` - -#### Custom SSL Certificates -```bash -# For custom certificates, place in: -# ~/hops/config/traefik/certs/ -# - yourdomain.com.crt -# - yourdomain.com.key - -# Update Traefik configuration to use custom certs -``` - -## 🆘 Troubleshooting - -### Common Issues & Solutions - -#### Docker Issues - -**Docker Not Starting:** -```bash -# Check Docker status -systemctl status docker - -# Restart Docker -sudo systemctl restart docker - -# Check Docker logs -journalctl -u docker --since "1 hour ago" - -# Reinstall Docker (Linux) -curl -fsSL https://get.docker.com | sh -sudo usermod -aG docker $USER -newgrp docker -``` - -**Docker Compose Errors:** -```bash -# Validate compose file -docker compose config - -# Check for syntax errors -docker compose config --quiet - -# Force recreate containers -docker compose up -d --force-recreate -``` - -#### Service-Specific Issues - -**Service Won't Start:** -```bash -# Check service logs -docker compose logs [service-name] - -# Check container status -docker compose ps - -# Restart service -docker compose restart [service-name] - -# Check port conflicts -sudo lsof -i :[port-number] -``` - -**Permission Issues:** -```bash -# Fix ownership (Linux) sudo chown -R $USER:$USER /opt/appdata sudo chown -R $USER:$USER /mnt/media -sudo chown -R $USER:$USER ~/hops - -# Fix ownership (macOS) -sudo chown -R $USER:$USER ~/hops/config -sudo chown -R $USER:$USER ~/hops/media - -# Check PUID/PGID values -id $USER # Should match PUID/PGID in .env -``` - -**Database Issues:** -```bash -# Reset service database (example: Sonarr) -docker compose down sonarr -rm -rf ~/hops/config/sonarr/sonarr.db* # macOS -rm -rf /opt/appdata/sonarr/sonarr.db* # Linux -docker compose up -d sonarr -``` - -#### Network Issues - -**Can't Access Services:** -```bash -# Check if services are running -docker compose ps - -# Check port mapping -docker compose port jellyfin 8096 - -# Check firewall (Linux) -sudo ufw status - -# Check local firewall (macOS) -# System Preferences → Security & Privacy → Firewall - -# Find container IP -docker inspect jellyfin | grep IPAddress -``` - -**Reverse Proxy Issues:** -```bash -# Check proxy logs -docker compose logs traefik -docker compose logs nginx-proxy-manager - -# Verify DNS resolution -nslookup yourdomain.com - -# Check certificate status -openssl s_client -connect yourdomain.com:443 -servername yourdomain.com -``` - -#### Platform-Specific Issues - -**macOS Issues:** -```bash -# Docker Desktop not starting -open /Applications/Docker.app - -# Homebrew issues -brew doctor -brew update && brew upgrade - -# Fix keychain authentication -security unlock-keychain ~/Library/Keychains/login.keychain -``` - -**Windows/WSL2 Issues:** -```bash -# WSL2 not starting -wsl --shutdown -wsl -d Ubuntu-22.04 - -# Docker Desktop WSL2 integration -# Check Docker Desktop → Settings → Resources → WSL Integration - -# File permission issues -# Ensure files are in WSL2 filesystem, not /mnt/c/ -``` - -### Log Analysis - -#### Log Locations -- **Installation Logs**: - - Linux: `/var/log/hops/` - - macOS: `/usr/local/var/log/hops/` - - Windows: `~/hops/logs/` -- **Service Logs**: `docker compose logs [service-name]` -- **System Logs**: `journalctl -u docker` - -#### Log Analysis Commands -```bash -# HOPS installation logs -sudo tail -f /var/log/hops/hops-main-*.log - -# Service logs with filtering -docker compose logs jellyfin | grep -i error -docker compose logs --since="1h" sonarr -docker compose logs --tail=100 radarr - -# System resource logs -dmesg | grep -i memory -journalctl --since="1 hour ago" | grep docker -``` - -### Recovery Procedures - -#### Service Recovery -```bash -# Stop problematic service -docker compose stop [service-name] - -# Remove container (keeps data) -docker compose rm [service-name] - -# Recreate service -docker compose up -d [service-name] - -# Full service reset (destroys data) -docker compose down [service-name] -rm -rf /path/to/service/config -docker compose up -d [service-name] -``` - -#### Complete System Recovery -```bash -# Stop all services -docker compose down - -# Backup current state -sudo tar -czf hops-backup-$(date +%Y%m%d).tar.gz ~/hops /opt/appdata - -# Clean Docker system -docker system prune -a -docker volume prune - -# Restart from backup -cd ~/hops -docker compose up -d - -# Or reinstall HOPS -sudo ./uninstall -sudo ./setup -``` - -## 📊 Performance Tuning - -### Resource Monitoring -```bash -# Container resource usage -docker stats - -# System resource usage -htop -iotop -free -h -df -h - -# Service-specific monitoring -docker compose exec portainer sh -# Access Portainer for detailed monitoring -``` - -### Optimization Strategies - -#### For Low-Resource Systems (2-4GB RAM) -```bash -# Recommended minimal stack -# - Jellyfin (media server) -# - qBittorrent (download) -# - Sonarr (TV management) -# - Portainer (monitoring) - -# Resource limits in docker-compose.yml -services: - jellyfin: - mem_limit: 1g - cpus: '2' - - sonarr: - mem_limit: 512m - cpus: '1' -``` - -#### For High-Performance Systems (8GB+ RAM) -```bash -# Full stack deployment -# Enable GPU transcoding -# Use multiple download clients -# Add monitoring stack - -# GPU support (Linux only) -# Intel GPU passthrough automatically configured -devices: - - /dev/dri:/dev/dri -``` - -#### Storage Optimization -```bash -# Use SSD for application data -# HDD for media storage -# Separate Docker volumes - -# Example optimized storage layout -/opt/appdata -> SSD -/mnt/media -> HDD array -~/hops -> SSD -``` - -### Update Management -```bash -# Automated updates with Watchtower -# Configure update schedule -WATCHTOWER_SCHEDULE=0 0 2 * * * # 2 AM daily - -# Manual update process -docker compose pull -docker compose up -d - -# Rollback to previous version -docker compose down -docker tag service:latest service:backup -docker pull service:previous -docker compose up -d -``` - -## 🔧 Advanced Features - -### Custom Service Definitions -```bash -# Add custom services to docker-compose.yml -services: - custom-service: - image: custom/image:latest - container_name: custom-service - environment: - - PUID=${PUID} - - PGID=${PGID} - - TZ=${TZ} - volumes: - - ${CONFIG_ROOT}/custom:/config - - ${DATA_ROOT}:/data - ports: - - "8999:8999" - restart: unless-stopped - networks: - - homelab -``` - -### Backup Automation -```bash -# Automated backup script -#!/bin/bash -DATE=$(date +%Y%m%d_%H%M%S) -BACKUP_DIR="/backup/hops" - -# Create backup directory -mkdir -p "$BACKUP_DIR" - -# Backup configurations -tar -czf "$BACKUP_DIR/config-$DATE.tar.gz" /opt/appdata - -# Backup compose files -cp ~/hops/.env ~/hops/docker-compose.yml "$BACKUP_DIR/" - -# Backup encrypted secrets -./lib/secrets.sh backup "$BACKUP_DIR/secrets-$DATE.enc" - -# Clean old backups (keep 7 days) -find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete -``` - -### Development & Testing -```bash -# Development setup -git clone https://github.com/skiercm/hops.git -cd hops - -# Syntax validation -bash -n lib/*.sh -bash -n *.sh - -# Test service definitions -./services-improved list -./services-improved generate jellyfin - -# Test installation in VM/container -# Use test environment before production deployment ``` --- -For installation guides, see [INSTALLATION.md](INSTALLATION.md). -For service information, see [SERVICES.md](SERVICES.md). \ No newline at end of file +For installation, see [INSTALLATION.md](INSTALLATION.md). +For troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md). diff --git a/INSTALLATION.md b/INSTALLATION.md index e2e33f3..11e5d69 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,365 +1,62 @@ # Installation Guide -This guide provides detailed installation instructions for all supported platforms. +> **Note**: This document is being rebuilt alongside the 1.0.0 codebase. +> Content will be expanded as features are stabilized. -## 🔧 System Requirements +## System Requirements -### Minimum Requirements -- **RAM**: 2GB (4GB+ recommended) -- **Storage**: 10GB free space (more for media storage) +- **OS**: Ubuntu 20.04+, Debian 11+, or Linux Mint 20+ (x86_64) +- **RAM**: 2GB minimum, 4GB+ recommended +- **Storage**: 10GB free (more for media) - **CPU**: 2 cores recommended -- **Network**: Internet connection required +- **Access**: sudo privileges -### Platform-Specific Requirements +## Installation -#### Linux (Ubuntu/Debian/Mint) -- **OS**: Ubuntu 20.04+, Debian 11+, or Linux Mint 20+ -- **Architecture**: x86_64 -- **Access**: Root/sudo privileges -- **Dependencies**: Automatically installed - -#### macOS -- **OS**: macOS 11.0+ (Big Sur) -- **Architecture**: Intel (x86_64) or Apple Silicon (ARM64) -- **Access**: Admin privileges (sudo) -- **Dependencies**: Homebrew and Docker Desktop installed automatically - -#### Windows (WSL2) -- **OS**: Windows 10 (build 19041+) or Windows 11 -- **WSL**: WSL2 enabled with Ubuntu 20.04+ distribution -- **Docker**: Docker Desktop with WSL2 backend -- **Access**: Admin access for initial setup -- **Architecture**: x86_64 with virtualization support -- **BIOS**: Hyper-V and virtualization enabled - -⚠️ **Note**: Windows support has limited testing. Proceed with caution and ensure backups. - -## 🐧 Linux Installation - -### Quick Install ```bash -# Download HOPS -git clone https://github.com/skiercm/hops.git +git clone https://git.canadabot.net/canadabot/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 # User operations -./user-operations deploy # Deploy services - -# Legacy method (still supported) +chmod +x hops install uninstall sudo ./hops ``` -### What Gets Installed -- Docker Engine (via official Docker script) -- Docker Compose -- Required system packages -- UFW firewall rules (automatic) -- Service directories and permissions +HOPS will install Docker automatically if not present, then walk you through +selecting and deploying services interactively. + +## Directory Structure -### Directory Structure ``` -~/hops/ # Main deployment directory -├── docker-compose.yml # Service definitions -├── .env # Environment variables -└── logs/ # Application logs +~/hops/ # Deployment directory +├── docker-compose.yml # Generated service definitions +├── .env # Environment variables and secrets +└── logs/ # HOPS logs -/opt/appdata/ # Application configurations +/opt/appdata/ # Application config data ├── jellyfin/ ├── sonarr/ └── [other services]/ -/mnt/media/ # Media storage +/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: +## Post-Installation ```bash -# Optional: Install Homebrew (will be done automatically) -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +# Check service status +cd ~/hops && docker compose ps -# Optional: Install Docker Desktop (will be done automatically) -brew install --cask docker -``` +# View logs +docker compose logs -f [service-name] -### 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 +# Access management interface sudo ./hops ``` -- **Compatibility**: Original installation method -- **Full-Featured**: Complete management interface -- **Reliability**: Extensively tested method -## 🔍 Post-Installation Verification +## Getting Help -### 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. \ No newline at end of file +- Issues: [git.canadabot.net/canadabot/hops/issues](https://git.canadabot.net/canadabot/hops/issues) +- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 42de046..52e99bb 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -1,314 +1,95 @@ -# HOPS Troubleshooting Guide +# Troubleshooting -This document provides solutions to common issues encountered when installing and running HOPS. +## Docker Not Starting -## Docker Repository Issues - -### Linux Mint Docker Repository Error - -**Symptoms:** -``` -E: The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file. -N: Updating from such a repository can't be done securely, and is therefore disabled by default. -``` - -**Root Cause:** -Linux Mint uses its own codenames (e.g., "xia", "vera", "vanessa") that don't exist in Docker's Ubuntu repositories. Docker only supports Ubuntu codenames like "noble", "jammy", "focal". - -**Solution:** -This issue has been resolved in HOPS v3.3.0+. The system now automatically detects the correct Ubuntu codename for Linux Mint installations using `UBUNTU_CODENAME` from `/etc/os-release`. - -**Manual Fix (if needed):** -1. **Clean existing Docker repositories:** - ```bash - sudo rm -f /etc/apt/sources.list.d/docker* - sudo rm -f /etc/apt/sources.list.d/*docker* - sudo rm -f /usr/share/keyrings/docker* - sudo rm -f /etc/apt/keyrings/docker* - sudo apt clean - ``` - -2. **Verify Ubuntu codename detection:** - ```bash - grep '^UBUNTU_CODENAME=' /etc/os-release - # Should return: UBUNTU_CODENAME=noble (for Linux Mint 22.x) - ``` - -3. **Update HOPS to latest version:** - ```bash - cd ~/hops - git pull - sudo ./hops --update - ``` - -### Docker Installation Fails - -**Symptoms:** -- `Package 'docker-ce' has no installation candidate` -- `Cannot connect to the Docker daemon at unix:///var/run/docker.sock` - -**Solutions:** - -1. **Check Docker service status:** - ```bash - sudo systemctl status docker - sudo systemctl status docker.socket - ``` - -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 +sudo systemctl status docker +sudo systemctl restart docker +journalctl -u docker --since "1 hour ago" ``` -### 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:** +If Docker is missing or broken: ```bash -sudo tail -f /var/log/hops/hops-main-*.log +curl -fsSL https://get.docker.com | sh +sudo usermod -aG docker $USER +newgrp docker ``` -**macOS:** +## Linux Mint: Docker Repository Error + +**Symptom:** `The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file` + +Linux Mint uses its own codenames that Docker's repo doesn't recognise. HOPS +detects the underlying Ubuntu codename via `UBUNTU_CODENAME` in `/etc/os-release`. + +Manual fix: ```bash -sudo tail -f /usr/local/var/log/hops/hops-main-*.log +sudo rm -f /etc/apt/sources.list.d/docker* /etc/apt/keyrings/docker* +sudo apt clean +grep '^UBUNTU_CODENAME=' /etc/os-release # confirm value is present +sudo ./hops # re-run installation ``` -### Docker Compose Logs +## Permission Denied + +```bash +# Docker socket access +sudo usermod -aG docker $USER +newgrp docker + +# Directory ownership +sudo chown -R $USER:$USER ~/hops +sudo chown -R $USER:$USER /opt/appdata +``` + +## Service Won't Start ```bash cd ~/hops -sudo docker compose logs -f [service-name] +docker compose logs [service-name] +docker compose ps +docker compose restart [service-name] ``` -### System Information - -When reporting issues, include: +## Port Already in Use + +```bash +sudo lsof -i :[port] +sudo ss -tlnp | grep :[port] +``` + +## Cannot Access Service Web UI + +1. Confirm container is running: `docker compose ps` +2. Check for port conflicts (above) +3. Check firewall: `sudo ufw status` +4. Allow port if needed: `sudo ufw allow [port]/tcp` + +## Docker Network Errors + +```bash +# Remove conflicting networks and recreate +sudo docker network rm traefik homelab +cd ~/hops && docker compose up -d +``` + +## Log Locations + +- **HOPS logs**: `/var/log/hops/hops-main-*.log` +- **Service logs**: `docker compose logs [service-name]` +- **System logs**: `journalctl -u docker` + +## Reporting Issues + +Collect this info before reporting: ```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 +cd ~/hops && 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 -``` \ No newline at end of file +Report at: [git.canadabot.net/canadabot/hops/issues](https://git.canadabot.net/canadabot/hops/issues)