Files

T

2025-07-12 06:53:40 -04:00

9.1 KiB

Raw Blame History

HOPS - Homelab Orchestration Provisioning Script

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.

🎯 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

✨ Key Features

🚀 Easy Installation

One-command installation process
Automatic Docker installation and configuration
Interactive service selection
Intelligent dependency resolution

🔒 Security First

Automatic firewall configuration
Secure password generation
File permission hardening
Network isolation

📊 Management & Monitoring

Real-time service status monitoring
Centralized log viewing
Easy service management (start/stop/restart)
Health checks and service verification

🔄 Reliability

Error handling with automatic rollback
Service dependency management
Port conflict detection
System requirements validation

📱 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

⬇️ 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
Authelia - Authentication and authorization server

📈 Monitoring & Management

Portainer - Docker container management
Uptime Kuma - Service monitoring
Watchtower - Automatic container updates

🔧 System Requirements

Minimum Requirements

OS: Ubuntu 20.04+, Debian 11+, or Linux Mint 20+
RAM: 2GB (4GB+ recommended)
Storage: 10GB free space (more for media)
CPU: 2 cores recommended
Network: Internet connection required

Prerequisites

Root/sudo access
x86_64 architecture

🚀 Quick Start

1. Download HOPS

git clone https://github.com/skiercm/hops.git
cd hops
chmod +x hops.sh

2. Run Installation

sudo ./hops.sh

3. Follow the Interactive Setup

Select your desired services
Configure directories and timezone
Choose security options
Wait for automated deployment

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

~/homelab/                    # Main homelab 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:

sudo ./hops.sh

Available Options:

Install HOPS - Deploy new services
Uninstall HOPS - Complete removal with options
Manage Services - Start/stop/restart services
Service Status - Real-time service monitoring
Access Information - Get service URLs and credentials
View Logs - Centralized log viewing
Help & Documentation - Built-in help system

🔧 Advanced Configuration

Environment Variables

All configuration is stored in ~/homelab/.env:

# Core Configuration
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
DEFAULT_ADMIN_PASSWORD=...   # Generated secure password
DEFAULT_DB_PASSWORD=...      # Database password

# Optional: Custom domain
DOMAIN=yourdomain.com
ACME_EMAIL=admin@yourdomain.com

Service Management Commands

# Navigate to homelab directory
cd ~/homelab

# View running services
docker compose ps

# View logs
docker compose logs -f [service-name]

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

# Update all services
docker compose pull && docker compose up -d

# Stop all services
docker compose down

🔒 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

Post-Installation Security

Change Default Passwords: Update passwords in .env file
Configure Reverse Proxy: Set up Traefik or Nginx Proxy Manager
Enable Authentication: Configure Authelia for additional security
Regular Updates: Use Watchtower for automatic updates

🆘 Troubleshooting

Common Issues

Port Conflicts

# 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

# Check service logs
cd ~/homelab
docker compose logs [service-name]

# Restart service
docker compose restart [service-name]

Permission Issues

# 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

Check the built-in help: sudo ./hops.sh → Option 7
Review logs in /var/log/hops/
Verify Docker status: systemctl status docker
Check service health: docker compose ps

🔄 Backup and Recovery

Backup Important Data

# Backup configurations
sudo tar -czf hops-config-backup.tar.gz /opt/appdata

# Backup compose files
cp ~/homelab/.env ~/homelab/docker-compose.yml /backup/location/

Recovery

# Restore configurations
sudo tar -xzf hops-config-backup.tar.gz -C /

# Redeploy services
cd ~/homelab
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:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Development Setup

git clone https://github.com/skiercm/hops.git
cd hops
# Make changes to scripts
# Test with: sudo ./hops.sh

📄 License

This project is licensed under the MIT License - see the 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

📞 Support

Documentation: Check this README and built-in help
Issues: Report bugs via GitHub Issues
Community: Join discussions in GitHub Discussions

Made with ❤️ for the homelab community

HOPS - Making homelab deployment simple, secure, and reliable.

9.1 KiB Raw Blame History