canadabot/hops
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rename scripts for clarity and add Huntarr service

Browse Source 
- Renamed all scripts to descriptive names without prefixes:
  • hops.sh → hops (main script)
  • hops_installer_enhanced.sh → install
  • hops_uninstaller_fixed.sh → uninstall
  • hops_service_definitions.sh → services
  • hops_install.sh → setup
  • hops_privileged_setup.sh → privileged-setup
  • hops_user_operations.sh → user-operations
  • hops_service_definitions_improved.sh → services-improved

- Added Huntarr service support:
  • Docker image: ghcr.io/plexguide/huntarr:latest
  • Port: 9705 with /health endpoint
  • Missing media discovery and automation
  • Integrates with *arr stack services
  • Added to installer menu as option 8

- Updated all script references and documentation
- Updated service categories in README and CLAUDE.md

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Stephen Klein
2025-07-17 21:52:22 -04:00
parent 721f7d7a75
commit 5affcd2e26
17 changed files with 1077 additions and 3678 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+114 -23
View File
@@ -6,54 +6,85 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
HOPS (Homelab Orchestration Provisioning Script) is a comprehensive automation tool for deploying homelab infrastructure using Docker Compose. It provides menu-driven installation, management, and monitoring of popular homelab services including media servers, download clients, monitoring tools, and more.
**Cross-Platform Support**: HOPS now supports both Linux (Ubuntu/Debian/Mint) and macOS systems with intelligent platform detection and abstraction.
## Architecture
### Core Components
- **Main Script (`hops.sh`)**: Primary entry point providing menu-driven interface for all operations
- **Installer (`hops_installer_enhanced.sh`)**: Handles service installation and Docker Compose deployment
- **Uninstaller (`hops_uninstaller_fixed.sh`)**: Manages complete removal of services and configurations
- **Service Definitions (`hops_service_definitions.sh`)**: Contains Docker Compose service templates and configurations
- **Installer (`install`)**: Handles service installation and Docker Compose deployment
- **Uninstaller (`uninstall`)**: Manages complete removal of services and configurations
- **Service Definitions (`services`)**: Contains Docker Compose service templates and configurations
- **Library System (`lib/`)**: Modular abstraction layer for cross-platform compatibility
- `lib/common.sh`: Shared logging, UI, and utility functions
- `lib/system.sh`: OS detection, system requirements, and platform abstraction
### Key Design Patterns
- **Modular Architecture**: Each major function is separated into dedicated scripts
- **Cross-Platform Abstraction**: OS-specific operations are abstracted through lib/system.sh
- **Service-Driven**: All services are defined as Docker Compose configurations with standardized patterns
- **Error Handling**: Comprehensive error handling with logging and rollback capabilities
- **Security First**: Built-in security hardening, firewall configuration, and secure password generation
- **Security First**: Built-in security hardening, platform-appropriate firewall configuration, and secure password generation
## Development Commands
### Running HOPS
```bash
# Main script (requires root)
# Main script (requires root on Linux, admin on macOS)
sudo ./hops.sh
# Direct installation
sudo ./hops_installer_enhanced.sh
# Direct installation (Linux)
sudo ./install
# Direct installation (macOS)
sudo ./install
# Uninstallation
sudo ./hops_uninstaller_fixed.sh
sudo ./uninstall
```
### Platform-Specific Requirements
**Linux (Ubuntu/Debian/Mint):**
- Root/sudo access
- Internet connection
- 2GB+ RAM, 10GB+ disk space
**macOS:**
- Admin access
- Internet connection
- 2GB+ RAM, 10GB+ disk space
- Homebrew will be installed automatically if not present
- Docker Desktop will be installed automatically via Homebrew
### Testing and Validation
```bash
# Check script syntax
bash -n hops.sh
bash -n hops_installer_enhanced.sh
bash -n hops_service_definitions.sh
bash -n hops_uninstaller_fixed.sh
bash -n install
bash -n services
bash -n uninstall
bash -n lib/system.sh
bash -n lib/common.sh
# Test OS detection and system requirements
source lib/common.sh && source lib/system.sh && detect_os && check_system_requirements 2 10
# Test service definitions
source hops_service_definitions.sh
source services
generate_service_definition jellyfin
```
### Log Management
```bash
# View installation logs
# View installation logs (Linux)
sudo tail -f /var/log/hops/hops-main-*.log
# View installation logs (macOS)
sudo tail -f /usr/local/var/log/hops/hops-main-*.log
# View Docker Compose logs
cd ~/homelab && docker compose logs -f [service-name]
```
@@ -63,13 +94,16 @@ cd ~/homelab && docker compose logs -f [service-name]
### Service Definition Pattern
All services follow a standardized Docker Compose pattern:
- LinuxServer.io containers with PUID/PGID/TZ environment variables
- Consistent volume mounting (`/opt/appdata` for configs, `/mnt/media` for data)
- Platform-aware volume mounting:
- **Linux**: `/opt/appdata` for configs, `/mnt/media` for data
- **macOS**: `/Users/[user]/homelab/config` for configs, `/Users/[user]/homelab/media` for data
- Health checks for web services
- Unified network configuration (`homelab` network)
- Restart policy: `unless-stopped`
- Platform-specific features (timezone mounts, GPU access) handled automatically
### Supported Service Categories
1. **Media Management**: Sonarr, Radarr, Lidarr, Readarr, Bazarr, Prowlarr, Tdarr
1. **Media Management**: Sonarr, Radarr, Lidarr, Readarr, Bazarr, Prowlarr, Tdarr, Huntarr
2. **Download Clients**: qBittorrent, Transmission, NZBGet, SABnzbd
3. **Media Servers**: Jellyfin, Plex, Emby, Jellystat
4. **Request Management**: Overseerr, Jellyseerr, Ombi
@@ -78,6 +112,7 @@ All services follow a standardized Docker Compose pattern:
## File Structure
### Linux File Structure
```
~/homelab/ # Main deployment directory
├── docker-compose.yml # Generated service definitions
@@ -94,6 +129,21 @@ All services follow a standardized Docker Compose pattern:
└── downloads/
```
### macOS File Structure
```
~/homelab/ # Main deployment directory
├── docker-compose.yml # Generated service definitions
├── .env # Environment variables
├── logs/ # Application logs
├── config/ # Application configurations
│ └── [service-name]/ # Individual service configs
└── media/ # Media storage
├── movies/
├── tv/
├── music/
└── downloads/
```
## Environment Configuration
Key environment variables in `~/homelab/.env`:
@@ -105,7 +155,9 @@ Key environment variables in `~/homelab/.env`:
## Security Features
- **Firewall Integration**: Automatic UFW rule management
- **Firewall Integration**:
- **Linux**: Automatic UFW rule management
- **macOS**: Manual firewall configuration (automatic setup skipped)
- **Secure Password Generation**: Cryptographically secure passwords
- **File Permission Hardening**: Restrictive permissions on sensitive files
- **Network Isolation**: Docker network segregation
@@ -113,7 +165,9 @@ Key environment variables in `~/homelab/.env`:
## Error Handling
- **Comprehensive Logging**: All operations logged to `/var/log/hops/`
- **Comprehensive Logging**: All operations logged to platform-specific directories
- **Linux**: `/var/log/hops/`
- **macOS**: `/usr/local/var/log/hops/`
- **Rollback Capability**: Automatic rollback on deployment failure
- **Dependency Validation**: Pre-deployment system requirement checks
- **Service Health Monitoring**: Built-in health checks for all services
@@ -126,35 +180,72 @@ Key environment variables in `~/homelab/.env`:
- `show_service_status()`: Real-time monitoring
- `show_access_info()`: Service URL and credential display
### In `hops_service_definitions.sh`
### In `services`
- `generate_service_definition()`: Creates Docker Compose service blocks
- `get_linuxserver_env()`: Standard environment variables
- `get_web_healthcheck()`: Health check configurations
- `get_timezone_mount()`: Platform-specific timezone handling
- `get_gpu_devices()`: Platform-specific GPU access
### In `hops_installer_enhanced.sh`
### In `install`
- Service selection and dependency resolution
- Docker Compose file generation
- Cross-platform dependency installation
- Security hardening implementation
- Post-deployment verification
### In `lib/system.sh`
- `detect_os()`: Cross-platform OS detection
- `check_system_requirements()`: Platform-aware system validation
- `install_package()`: Package manager abstraction
- `install_docker()`: Platform-specific Docker installation
- `get_primary_ip()`: Network interface detection
- `get_default_*_path()`: Platform-specific path resolution
## Development Guidelines
- **Bash Best Practices**: Use `set -e` for error handling, quote variables, use readonly for constants
- **Cross-Platform Compatibility**: Always use lib/system.sh abstraction functions instead of direct OS commands
- **Logging**: Use the logging functions (`log`, `error_exit`, `warning`, `success`, `info`)
- **Color Output**: Use predefined color constants for consistent formatting
- **Service Patterns**: Follow the established Docker Compose patterns when adding new services
- **Security**: Never commit secrets, use secure password generation, implement proper file permissions
- **Path Handling**: Use `get_default_*_path()` functions for platform-specific paths
## Common Operations
### Adding New Services
1. Add service definition function in `hops_service_definitions.sh`
2. Add service to installer menu in `hops_installer_enhanced.sh`
1. Add service definition function in `services`
2. Add service to installer menu in `install`
3. Configure any required dependencies or special handling
4. Test deployment and health checks
### Debugging Issues
1. Check logs in `/var/log/hops/`
1. Check logs in platform-specific directories:
- **Linux**: `/var/log/hops/`
- **macOS**: `/usr/local/var/log/hops/`
2. Verify Docker Compose syntax with `docker compose config`
3. Check service health with `docker compose ps`
4. Review firewall rules with `sudo ufw status`
4. Review firewall rules:
- **Linux**: `sudo ufw status`
- **macOS**: Check System Preferences > Security & Privacy > Firewall
## Platform-Specific Notes
### macOS Considerations
- **Architecture Support**: Both Intel (x86_64) and Apple Silicon (ARM64) are supported
- **Docker Desktop**: Automatically installed via Homebrew if not present
- **Homebrew**: Automatically installed if not present
- **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 structure for better compatibility
- **Service Management**: Uses launchctl instead of systemctl where applicable
### Linux Considerations
- **Architecture Support**: x86_64 only
- **Docker Engine**: Installed via official Docker script
- **Package Management**: Uses apt-get for Ubuntu/Debian/Mint
- **GPU Acceleration**: Available for Intel GPUs via /dev/dri passthrough
- **Firewall**: Automatic UFW configuration
- **File Permissions**: Uses system-wide directories (/opt, /mnt)
- **Service Management**: Uses systemctl for service management