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

Stub out stale documentation, rebuild as Linux-only

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Stephen Klein
2026-06-10 21:17:16 -04:00
parent 148a0827e3
commit a7213441da
3 changed files with 130 additions and 1303 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INSTALLATION.md
+29 -332
View File
@@ -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 <services> # 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.
- Issues: [git.canadabot.net/canadabot/hops/issues](https://git.canadabot.net/canadabot/hops/issues)
- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)