hops/INSTALLATION.md

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

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

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

# 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

# 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

# Run in PowerShell as Administrator
wsl --install
# Restart computer when prompted

Step 2: Install Ubuntu Distribution

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

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

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

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

sudo ./hops

• Compatibility: Original installation method
• Full-Featured: Complete management interface
• Reliability: Extensively tested method

🔍 Post-Installation Verification

Check Service Status

# 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

# 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

# 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

# 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

# Check what's using a port
sudo lsof -i :PORT_NUMBER

# Kill conflicting process
sudo kill -9 PID

WSL2 Issues (Windows)

# 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

# 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

# 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 for configuration and troubleshooting details.