HOPS - Homelab Orchestration Provisioning Script

Overview

HOPS (Homelab Orchestration Provisioning Script) is a powerful automation tool designed to simplify the deployment and management of Docker-based homelab services. With a focus on security, ease of use, and cross-platform compatibility, HOPS enables users to quickly set up comprehensive media management, download clients, reverse proxies, and monitoring solutions.

Key Features

🚀 Easy Installation

Simple one-command installation with automatic dependency management and platform detection.

🔒 Security First

Automatic hardening, encrypted secret management, privilege separation, and secure defaults.

🔄 Auto-Updates

Automatic update system with safe update mechanisms and change tracking.

🌐 Cross-Platform

Supports Linux (stable), macOS (improved), and Windows WSL2 (limited) environments.

📦 Comprehensive Services

Pre-configured services across media management, downloads, servers, and monitoring.

⚙️ Modular Architecture

Flexible service selection and configuration with easy customization options.

What's New in v3.3.0

Automatic Updates: Built-in update system with safe update mechanisms
CLI Flags: Enhanced command-line interface with new flags and options
Change Tracking: Detailed logging of system changes and modifications
Improved macOS Support: Better compatibility and automatic dependency handling

Quick Start

Get started with HOPS in just a few commands:

# Download and install HOPS curl -fsSL https://github.com/homelab-ops/hops/raw/main/install | bash # Navigate to HOPS directory cd ~/hops # Run setup ./setup # Start services ./hops start

✅ Directory Structure: HOPS installs to ~/hops with all configurations, data, and services organized in subdirectories.

Services

HOPS provides a comprehensive suite of pre-configured services for your homelab:

📺 Media Management (*arr Stack) ▼

Sonarr

TV series management and monitoring

Port: 8989

Radarr

Movie collection management

Port: 7878

Lidarr

Music collection manager

Port: 8686

Readarr

Book and audiobook management

Port: 8787

Bazarr

Subtitle management for Sonarr and Radarr

Port: 6767

Prowlarr

Indexer manager/proxy

Port: 9696

⬇️ Download Clients ▼

qBittorrent

Feature-rich BitTorrent client

Port: 8080

Transmission

Lightweight BitTorrent client

Port: 9091

SABnzbd

Usenet binary downloader

Port: 8080

NZBGet

Efficient Usenet downloader

Port: 6789

🎬 Media Servers ▼

Jellyfin

Free software media server

Port: 8096

Plex

Popular media server platform

Port: 32400

Emby

Personal media server

Port: 8096

Jellystat

Statistics and monitoring for Jellyfin

Port: 3000

🔒 Reverse Proxy & Security ▼

Traefik

Modern reverse proxy with automatic SSL

Port: 80/443

Nginx Proxy Manager

Easy-to-use reverse proxy management

Port: 81

Caddy

Web server with automatic HTTPS

Port: 80/443

Authelia

Authentication and authorization server

Port: 9091

📊 Monitoring & Management ▼

Portainer

Docker container management UI

Port: 9000

Uptime Kuma

Self-hosted monitoring tool

Port: 3001

Watchtower

Automatic Docker container updates

N/A

System Requirements

🐧 Linux (Stable)

Ubuntu 20.04+ / Debian 11+ / CentOS 8+
2GB RAM minimum, 4GB recommended
20GB free storage
Docker support (auto-installed)

🍎 macOS (Improved)

macOS 10.15+ (Intel/Apple Silicon)
4GB RAM minimum, 8GB recommended
Docker Desktop (auto-installed)
Homebrew (auto-installed)

🪟 Windows WSL2 (Limited)

Windows 10 Build 19041+ / Windows 11
WSL2 enabled
Ubuntu 20.04+ in WSL2
Docker Desktop with WSL2 backend

Installation

🐧 Linux Installation ▼

Automatic Installation (Recommended)

# One-line install with automatic dependency management
curl -fsSL https://github.com/homelab-ops/hops/raw/main/install | bash
                            

Manual Installation

# Clone repository
git clone https://github.com/homelab-ops/hops.git ~/hops
cd ~/hops

# Make scripts executable
chmod +x setup install privileged-setup

# Run installation
./install
                            

🍎 macOS Installation ▼

Prerequisites: Xcode Command Line Tools will be automatically installed if not present.

# Automatic installation with dependency handling
curl -fsSL https://github.com/homelab-ops/hops/raw/main/install | bash

# HOPS will automatically install:
# - Homebrew (if not present)
# - Docker Desktop
# - Required dependencies
                            

Note: Docker Desktop installation may require manual approval and system restart.

🪟 Windows WSL2 Installation ▼

1. Enable WSL2

# Run in PowerShell as Administrator
wsl --install -d Ubuntu-20.04
wsl --set-default-version 2
                            

2. Install Docker Desktop

Download and install Docker Desktop with WSL2 backend enabled.

3. Install HOPS in WSL2

# Inside WSL2 Ubuntu
curl -fsSL https://github.com/homelab-ops/hops/raw/main/install | bash
                            

Limitations: Some features may not work correctly in WSL2. Native Linux installation is recommended for production use.

Management

HOPS provides a comprehensive command-line interface for managing your homelab services:

# Service Management
./hops start          # Start all enabled services
./hops stop           # Stop all services
./hops restart        # Restart all services
./hops status         # Show service status

# Individual Service Control
./hops start sonarr   # Start specific service
./hops stop jellyfin  # Stop specific service

# System Operations
./hops update         # Update HOPS and services
./hops backup         # Create system backup
./hops logs [service] # View service logs
                    

💡 Pro Tip: Use ./hops --help to see all available commands and options.

Troubleshooting

Common issues and solutions for HOPS deployment and management.

🐳 Docker Issues ▼

Docker Not Starting

# 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

# Validate compose file
docker compose config

# Force recreate containers
docker compose up -d --force-recreate
                            

🔒 Permission Issues ▼

Fix File Ownership

# Linux systems
sudo chown -R $USER:$USER /opt/appdata
sudo chown -R $USER:$USER /mnt/media
sudo chown -R $USER:$USER ~/hops

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

🌐 Network & Service Issues ▼

Can't Access Services

# Check if services are running
docker compose ps

# Check port mapping
docker compose port jellyfin 8096

# Check firewall (Linux)
sudo ufw status

# Find container IP
docker inspect jellyfin | grep IPAddress
                            

Service Won't Start

# Check service logs
docker compose logs [service-name]

# Restart specific service
docker compose restart [service-name]

# Check port conflicts
sudo lsof -i :[port-number]
                            

🍎 macOS Specific Issues ▼

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

# WSL2 not starting
wsl --shutdown
wsl -d Ubuntu-22.04

# Check Docker Desktop WSL2 integration
# Docker Desktop → Settings → Resources → WSL Integration
                            

Important: Ensure files are in WSL2 filesystem, not /mnt/c/ for optimal performance.

📝 Log Locations:

Linux: /var/log/hops/
macOS: /usr/local/var/log/hops/
Windows: ~/hops/logs/
Service Logs: docker compose logs [service-name]

Frequently Asked Questions

🚀 Getting Started ▼

What is HOPS?

HOPS (Homelab Orchestration Provisioning Script) is a comprehensive automation tool for deploying Docker-based homelab services. It simplifies the setup of media servers, download clients, monitoring tools, and more with security-first design.

What services does HOPS support?

HOPS supports 40+ services including:

Media: Jellyfin, Plex, Emby, Sonarr, Radarr, Lidarr
Downloads: qBittorrent, Transmission, SABnzbd, NZBGet
Reverse Proxy: Traefik, Nginx Proxy Manager, Caddy
Monitoring: Portainer, Uptime Kuma, Watchtower

How much does HOPS cost?

HOPS is completely free and open-source under the MIT license. All supported services are also free and open-source.

💻 System Requirements ▼

What are the minimum system requirements?

Minimum: 2GB RAM, 10GB storage, 2 CPU cores, internet connection

Recommended: 4GB+ RAM, 50GB+ storage (more for media), modern CPU

Which operating systems are supported?

Linux: Ubuntu 20.04+, Debian 11+, Linux Mint 20+ (✅ Stable)
macOS: 11.0+ Big Sur, Intel/Apple Silicon (✅ Improved)
Windows: 10/11 with WSL2 + Ubuntu (⚠️ Limited)

Can I run HOPS on a Raspberry Pi?

Yes! HOPS works on ARM64 systems including Raspberry Pi 4. Performance will vary based on services selected. Recommended: Pi 4 with 4GB+ RAM.

🔐 Security & Updates ▼

Is HOPS secure?

Yes! HOPS implements multiple security measures:

Encrypted secret management
Automatic firewall configuration
Privilege separation
Input validation and sanitization
Secure defaults for all services

How do I update HOPS?

sudo ./hops --update          # Update to latest version
sudo ./hops --check-updates   # Check for updates
                                

How do I update services?

./user-operations update      # Update all containers
docker compose pull          # Pull latest images
docker compose up -d         # Recreate with new images
                                

📁 Configuration & Customization ▼

Where are my media files stored?

Linux: /mnt/media/
macOS: ~/hops/media/
Windows/WSL2: /mnt/media/ (can link to Windows drives)

Where are service configurations stored?

Linux: /opt/appdata/
macOS: ~/hops/config/
Windows/WSL2: /opt/appdata/

Can I change service ports?

Yes! Edit the ~/hops/.env file or use the encrypted secret management:

./lib/secrets.sh update JELLYFIN_PORT 8097
docker compose up -d
                                

Can I add custom services?

Yes! Add custom service definitions to ~/hops/docker-compose.yml following the existing patterns. Ensure proper environment variables, volumes, and network configuration.

🐛 Support & Community ▼

Where do I get help?

HOPS Issues: GitHub Issues
General Discussion: GitHub Discussions
Service Issues: Contact individual service developers

When should I contact HOPS vs service developers?

Contact HOPS for: Installation issues, Docker Compose problems, cross-platform issues, HOPS script bugs

Contact Service Developers for: Service configuration, features, service-specific bugs, usage questions

How do I contribute to HOPS?

Contributions are welcome! Check the GitHub repository for contribution guidelines, submit bug reports, feature requests, or code improvements.

Advanced Configuration

🔐 Environment Variables & Secrets ▼

HOPS supports encrypted secret management for sensitive configuration:

# Set encrypted secrets
./hops secret set API_KEY "your-secret-key"
./hops secret set DB_PASSWORD "secure-password"

# List secrets (names only)
./hops secret list

# Remove secrets
./hops secret remove API_KEY
                            

🔒 Security Features ▼

Automatic Hardening: Secure defaults and permission management
Firewall Configuration: Automated UFW/iptables setup
File Permissions: Proper ownership and access controls
Network Isolation: Docker network segmentation
SSL/TLS: Automatic certificate management
Privilege Separation: Non-root service execution

🌐 Reverse Proxy Setup ▼

HOPS supports multiple reverse proxy solutions:

# Traefik (Automatic SSL)
./hops enable traefik
./hops config traefik domain mydomain.com

# Nginx Proxy Manager
./hops enable nginx-proxy-manager

# Caddy (User-provided Caddyfile required)
./hops enable caddy
                            

Changelog

🚀 Version 3.3.0 - Latest ▼

Added

Automatic update system with safe update mechanisms
Enhanced CLI with new flags and options
Detailed change tracking and logging
Improved error handling and recovery

Changed

Enhanced macOS compatibility and dependency handling
Improved service management and monitoring
Better Docker Desktop integration

📦 Version 3.2.0 ▼

Added

Caddy web server support
Enhanced macOS compatibility
Docker Desktop automatic installation
Improved service detection and management

🔐 Version 3.1.0-beta ▼

Added

Encrypted secret management system
Enhanced input validation and sanitization
Privilege separation for improved security
Modular architecture for better maintainability

Acknowledgements

HOPS would not be possible without the incredible work of the open-source community. We extend our heartfelt gratitude to the developers and maintainers of the individual services that make homelab automation possible:

📺 Media Management

Thanks to the teams behind Sonarr, Radarr, Lidarr, Readarr, Bazarr, and Prowlarr for creating the comprehensive *arr ecosystem that revolutionized media automation.

🎬 Media Servers

Grateful to the Jellyfin, Plex, and Emby teams for building powerful media streaming platforms that bring entertainment to our homes.

⬇️ Download Clients

Appreciation to the developers of qBittorrent, Transmission, SABnzbd, and NZBGet for creating reliable and efficient download solutions.

🔒 Infrastructure

Special thanks to the Traefik, Caddy, Nginx, and Authelia teams for building the networking and security foundation that keeps our services safe and accessible.

📊 Monitoring & Management

Recognition to the creators of Portainer, Uptime Kuma, Watchtower, and Jellystat for providing essential monitoring and management tools.

🐳 Docker Ecosystem

Immense gratitude to Docker Inc. and the entire containerization ecosystem. Without Docker's revolutionary technology, modern homelab automation simply wouldn't exist.

🙏 Community Impact: These projects represent thousands of hours of volunteer development work. Consider supporting the individual projects financially or through contributions if HOPS has been valuable to your homelab setup.

Without the dedication and innovation of these developers, none of this would be possible. Thank you for making the self-hosted community thrive.

Support & Community

📚 Documentation

Comprehensive guides and troubleshooting information available in the project repository.

🐛 Bug Reports

Report issues and bugs through GitHub Issues with detailed reproduction steps.

💬 Community

Join the community for discussions, tips, and assistance with homelab setups.

🔧 Service Issues

For service-specific problems, consult the individual service documentation and support channels.

⚠️ Important: For issues specific to individual services (Sonarr, Radarr, Jellyfin, etc.), please contact their respective support channels rather than HOPS support.

✅ HOPS Issues: Report installation problems, script errors, platform compatibility issues, or feature requests to HOPS directly.