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
ADVANCED.md
+23 -674
View File
@@ -1,715 +1,64 @@
# Advanced Configuration & Troubleshooting
# Advanced Configuration
This guide covers advanced HOPS configuration, troubleshooting, security features, and system administration.
This guide covers advanced HOPS configuration and system administration.
## 🔧 Advanced Configuration
> **Note**: This document is being rebuilt alongside the 1.0.0 codebase.
> Content will be expanded as features are stabilized.
### Environment Variables
## Environment Variables
HOPS uses both encrypted secret management and traditional environment files for configuration.
HOPS writes a `.env` file to `~/hops/` during installation. Key variables:
#### Encrypted Secret Management (v3.1.0+)
```bash
# Initialize secret management
./lib/secrets.sh init
# Create encrypted environment
./lib/secrets.sh create
# Update values
./lib/secrets.sh update DOMAIN example.com
./lib/secrets.sh update ACME_EMAIL admin@example.com
# Retrieve values
./lib/secrets.sh get PUID
./lib/secrets.sh get DEFAULT_ADMIN_PASSWORD
# List all keys
./lib/secrets.sh list
# Backup encrypted secrets
./lib/secrets.sh backup /backup/location/
```
#### Traditional Environment File (~/hops/.env)
```bash
# User and Group Configuration
PUID=1000 # User ID
PGID=1000 # Group ID
PUID=1000 # User ID (run: id -u)
PGID=1000 # Group ID (run: id -g)
TZ=America/New_York # Timezone
# Directory Configuration
DATA_ROOT=/mnt/media # Media storage (Linux)
CONFIG_ROOT=/opt/appdata # App configurations (Linux)
DATA_ROOT=/mnt/media # Media storage
CONFIG_ROOT=/opt/appdata # App configurations
# macOS paths (automatically set)
DATA_ROOT=/Users/username/hops/media
CONFIG_ROOT=/Users/username/hops/config
# Security (auto-generated and encrypted)
DEFAULT_ADMIN_PASSWORD=... # Generated secure password
DEFAULT_DB_PASSWORD=... # Database password
JELLYFIN_PASSWORD=... # Service-specific passwords
# Optional: Custom Domain Configuration
DOMAIN=yourdomain.com
ACME_EMAIL=admin@yourdomain.com
# Optional: Service Overrides
JELLYFIN_PORT=8096
SONARR_PORT=8989
RADARR_PORT=7878
DEFAULT_ADMIN_PASSWORD=... # Auto-generated
DEFAULT_DB_PASSWORD=... # Auto-generated
```
### Service-Specific Configuration
## Docker Compose Commands
#### Reverse Proxy Setup
**Traefik Configuration:**
```bash
# Traefik automatically configured with labels
# Custom configuration in ~/hops/config/traefik/
# Example dynamic configuration
mkdir -p ~/hops/config/traefik/dynamic
cat > ~/hops/config/traefik/dynamic/middleware.yml << 'EOF'
http:
middlewares:
default-headers:
headers:
frameDeny: true
sslRedirect: true
browserXssFilter: true
contentTypeNosniff: true
forceSTSHeader: true
stsIncludeSubdomains: true
stsPreload: true
stsSeconds: 31536000
EOF
```
**Nginx Proxy Manager:**
- Access admin interface on port 81
- Default credentials: `admin@example.com` / `changeme`
- Configure SSL certificates through web interface
**Caddy Configuration:**
```bash
# Create Caddy configuration directory
mkdir -p ~/hops/config/caddy
# Create custom Caddyfile
cat > ~/hops/config/caddy/Caddyfile << 'EOF'
# Global options
{
email your-email@domain.com
# Optional: Use custom CA
# acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}
# Main domain
yourdomain.com {
reverse_proxy jellyfin:8096
# Custom headers
header {
# Security headers
Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
X-Content-Type-Options "nosniff"
X-Frame-Options "DENY"
Referrer-Policy "strict-origin-when-cross-origin"
}
}
# Subdomain routing
sonarr.yourdomain.com {
reverse_proxy sonarr:8989
}
radarr.yourdomain.com {
reverse_proxy radarr:7878
}
# Internal services (authentication required)
portainer.yourdomain.com {
reverse_proxy portainer:9000
# Optional: IP allowlist
@internal {
remote_ip 192.168.1.0/24 10.0.0.0/8
}
handle @internal {
reverse_proxy portainer:9000
}
handle {
respond "Access denied" 403
}
}
EOF
```
#### Authelia Integration
```bash
# Authelia configuration
mkdir -p ~/hops/config/authelia
# Example configuration (simplified)
cat > ~/hops/config/authelia/configuration.yml << 'EOF'
theme: dark
default_redirection_url: https://yourdomain.com
server:
host: 0.0.0.0
port: 9091
log:
level: warn
authentication_backend:
file:
path: /config/users_database.yml
password:
algorithm: argon2id
access_control:
default_policy: deny
rules:
- domain: jellyfin.yourdomain.com
policy: bypass
- domain: "*.yourdomain.com"
policy: one_factor
session:
name: authelia_session
domain: yourdomain.com
regulation:
max_retries: 3
ban_time: 10m
storage:
local:
path: /config/db.sqlite3
notifier:
filesystem:
filename: /config/notification.txt
EOF
```
### Service Management Commands
#### User Operations Script (No Sudo Required)
```bash
# Service status and control
./user-operations status # View all service status
./user-operations status jellyfin # View specific service
./user-operations logs jellyfin # View service logs
./user-operations logs jellyfin -f # Follow logs
# Deployment operations
./user-operations deploy # Deploy all services
./user-operations stop # Stop all services
./user-operations restart # Restart all services
./user-operations restart jellyfin # Restart specific service
# Update operations
./user-operations update # Update all containers
./user-operations update jellyfin # Update specific container
```
#### Direct Docker Compose Commands
```bash
cd ~/hops
# Service management
docker compose ps # List services
docker compose up -d # Start all services
docker compose down # Stop all services
docker compose restart # Restart all services
docker compose restart jellyfin # Restart specific service
# Logs and monitoring
docker compose logs # View all logs
docker compose logs -f jellyfin # Follow specific service logs
docker compose logs --tail=100 sonarr # Last 100 lines
# Updates and maintenance
docker compose restart [service] # Restart a service
docker compose logs -f [service] # Follow logs
docker compose logs --tail=100 [service] # Last 100 lines
docker compose pull # Pull new images
docker compose up -d --force-recreate # Recreate containers
docker compose down && docker compose up -d # Full restart
# Resource monitoring
docker stats # Real-time resource usage
docker system df # Disk usage
docker system prune # Clean unused data
```
### New Modular Architecture
## Firewall
HOPS v3.1.0+ introduces a modular library system:
HOPS configures UFW automatically on Linux. Manual management:
```
hops/
├── lib/ # Shared libraries
│ ├── common.sh # Logging, UI, utilities
│ ├── system.sh # OS detection, requirements
│ ├── docker.sh # Docker operations
│ ├── security.sh # Security functions
│ ├── validation.sh # Input validation
│ ├── secrets.sh # Secret management
│ └── privileges.sh # Privilege separation
├── setup # Main installation wrapper
├── privileged-setup # Root-only operations
├── user-operations # User operations
├── services-improved # Enhanced service definitions
└── hops # Main script
```
#### Using Library Functions
```bash
# Source libraries in custom scripts
source lib/common.sh
source lib/system.sh
# Use logging functions
log "INFO" "Starting custom operation"
warning "This is a warning message"
error_exit "Fatal error occurred"
# Use system functions
detect_os
check_system_requirements 2 10 # 2GB RAM, 10GB disk
# Use validation functions
validate_port "8080"
validate_domain "example.com"
```
## 🔒 Security Features & Hardening
### Automatic Security Hardening
HOPS automatically implements several security measures:
#### Firewall Configuration (Linux)
```bash
# UFW rules automatically created
sudo ufw status
# Manual firewall management
sudo ufw allow 8096/tcp comment "Jellyfin"
sudo ufw allow 9000/tcp comment "Portainer"
sudo ufw delete allow 8096/tcp # Remove rule
sudo ufw delete allow 8096/tcp
```
#### File Permissions
```bash
# Automatic permission hardening
# Secrets: 600 (owner read/write only)
# Configs: 644 (owner write, group/other read)
# Scripts: 755 (executable)
## File Permissions
# Manual permission fixes
```bash
chmod 600 ~/hops/.env
chmod 644 ~/hops/docker-compose.yml
chmod 755 ~/hops/user-operations
```
#### Network Isolation
```bash
# Docker network isolation
docker network ls | grep homelab
docker network inspect homelab
# View network configuration
docker compose config | grep network
```
### Security Auditing
```bash
# Run security audit
./lib/security.sh audit
# Check for security issues
./lib/security.sh check-passwords
./lib/security.sh check-permissions
./lib/security.sh check-firewall
# Security recommendations
./lib/security.sh recommendations
```
### SSL/TLS Configuration
#### Traefik SSL
Traefik automatically handles SSL certificates with Let's Encrypt:
```bash
# Check certificate status
docker compose logs traefik | grep -i certificate
# Manual certificate renewal (if needed)
docker compose restart traefik
```
#### Custom SSL Certificates
```bash
# For custom certificates, place in:
# ~/hops/config/traefik/certs/
# - yourdomain.com.crt
# - yourdomain.com.key
# Update Traefik configuration to use custom certs
```
## 🆘 Troubleshooting
### Common Issues & Solutions
#### Docker Issues
**Docker Not Starting:**
```bash
# 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:**
```bash
# Validate compose file
docker compose config
# Check for syntax errors
docker compose config --quiet
# Force recreate containers
docker compose up -d --force-recreate
```
#### Service-Specific Issues
**Service Won't Start:**
```bash
# Check service logs
docker compose logs [service-name]
# Check container status
docker compose ps
# Restart service
docker compose restart [service-name]
# Check port conflicts
sudo lsof -i :[port-number]
```
**Permission Issues:**
```bash
# Fix ownership (Linux)
sudo chown -R $USER:$USER /opt/appdata
sudo chown -R $USER:$USER /mnt/media
sudo chown -R $USER:$USER ~/hops
# Fix ownership (macOS)
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
```
**Database Issues:**
```bash
# Reset service database (example: Sonarr)
docker compose down sonarr
rm -rf ~/hops/config/sonarr/sonarr.db* # macOS
rm -rf /opt/appdata/sonarr/sonarr.db* # Linux
docker compose up -d sonarr
```
#### Network Issues
**Can't Access Services:**
```bash
# Check if services are running
docker compose ps
# Check port mapping
docker compose port jellyfin 8096
# Check firewall (Linux)
sudo ufw status
# Check local firewall (macOS)
# System Preferences → Security & Privacy → Firewall
# Find container IP
docker inspect jellyfin | grep IPAddress
```
**Reverse Proxy Issues:**
```bash
# Check proxy logs
docker compose logs traefik
docker compose logs nginx-proxy-manager
# Verify DNS resolution
nslookup yourdomain.com
# Check certificate status
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com
```
#### Platform-Specific Issues
**macOS Issues:**
```bash
# 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:**
```bash
# WSL2 not starting
wsl --shutdown
wsl -d Ubuntu-22.04
# Docker Desktop WSL2 integration
# Check Docker Desktop → Settings → Resources → WSL Integration
# File permission issues
# Ensure files are in WSL2 filesystem, not /mnt/c/
```
### Log Analysis
#### 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`
#### Log Analysis Commands
```bash
# HOPS installation logs
sudo tail -f /var/log/hops/hops-main-*.log
# Service logs with filtering
docker compose logs jellyfin | grep -i error
docker compose logs --since="1h" sonarr
docker compose logs --tail=100 radarr
# System resource logs
dmesg | grep -i memory
journalctl --since="1 hour ago" | grep docker
```
### Recovery Procedures
#### Service Recovery
```bash
# Stop problematic service
docker compose stop [service-name]
# Remove container (keeps data)
docker compose rm [service-name]
# Recreate service
docker compose up -d [service-name]
# Full service reset (destroys data)
docker compose down [service-name]
rm -rf /path/to/service/config
docker compose up -d [service-name]
```
#### Complete System Recovery
```bash
# Stop all services
docker compose down
# Backup current state
sudo tar -czf hops-backup-$(date +%Y%m%d).tar.gz ~/hops /opt/appdata
# Clean Docker system
docker system prune -a
docker volume prune
# Restart from backup
cd ~/hops
docker compose up -d
# Or reinstall HOPS
sudo ./uninstall
sudo ./setup
```
## 📊 Performance Tuning
### Resource Monitoring
```bash
# Container resource usage
docker stats
# System resource usage
htop
iotop
free -h
df -h
# Service-specific monitoring
docker compose exec portainer sh
# Access Portainer for detailed monitoring
```
### Optimization Strategies
#### For Low-Resource Systems (2-4GB RAM)
```bash
# Recommended minimal stack
# - Jellyfin (media server)
# - qBittorrent (download)
# - Sonarr (TV management)
# - Portainer (monitoring)
# Resource limits in docker-compose.yml
services:
jellyfin:
mem_limit: 1g
cpus: '2'
sonarr:
mem_limit: 512m
cpus: '1'
```
#### For High-Performance Systems (8GB+ RAM)
```bash
# Full stack deployment
# Enable GPU transcoding
# Use multiple download clients
# Add monitoring stack
# GPU support (Linux only)
# Intel GPU passthrough automatically configured
devices:
- /dev/dri:/dev/dri
```
#### Storage Optimization
```bash
# Use SSD for application data
# HDD for media storage
# Separate Docker volumes
# Example optimized storage layout
/opt/appdata -> SSD
/mnt/media -> HDD array
~/hops -> SSD
```
### Update Management
```bash
# Automated updates with Watchtower
# Configure update schedule
WATCHTOWER_SCHEDULE=0 0 2 * * * # 2 AM daily
# Manual update process
docker compose pull
docker compose up -d
# Rollback to previous version
docker compose down
docker tag service:latest service:backup
docker pull service:previous
docker compose up -d
```
## 🔧 Advanced Features
### Custom Service Definitions
```bash
# Add custom services to docker-compose.yml
services:
custom-service:
image: custom/image:latest
container_name: custom-service
environment:
- PUID=${PUID}
- PGID=${PGID}
- TZ=${TZ}
volumes:
- ${CONFIG_ROOT}/custom:/config
- ${DATA_ROOT}:/data
ports:
- "8999:8999"
restart: unless-stopped
networks:
- homelab
```
### Backup Automation
```bash
# Automated backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/hops"
# Create backup directory
mkdir -p "$BACKUP_DIR"
# Backup configurations
tar -czf "$BACKUP_DIR/config-$DATE.tar.gz" /opt/appdata
# Backup compose files
cp ~/hops/.env ~/hops/docker-compose.yml "$BACKUP_DIR/"
# Backup encrypted secrets
./lib/secrets.sh backup "$BACKUP_DIR/secrets-$DATE.enc"
# Clean old backups (keep 7 days)
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete
```
### Development & Testing
```bash
# Development setup
git clone https://github.com/skiercm/hops.git
cd hops
# Syntax validation
bash -n lib/*.sh
bash -n *.sh
# Test service definitions
./services-improved list
./services-improved generate jellyfin
# Test installation in VM/container
# Use test environment before production deployment
```
---
For installation guides, see [INSTALLATION.md](INSTALLATION.md).
For service information, see [SERVICES.md](SERVICES.md).
For installation, see [INSTALLATION.md](INSTALLATION.md).
For troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
INSTALLATION.md
+28 -331
View File
@@ -1,78 +1,37 @@
# 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]/
@@ -84,282 +43,20 @@ sudo ./hops
└── 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)
TROUBLESHOOTING.md
+70 -289
View File
@@ -1,314 +1,95 @@
# HOPS Troubleshooting Guide
# Troubleshooting
This document provides solutions to common issues encountered when installing and running HOPS.
## Docker Not Starting
## Docker Repository Issues
### Linux Mint Docker Repository Error
**Symptoms:**
```
E: The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
```
**Root Cause:**
Linux Mint uses its own codenames (e.g., "xia", "vera", "vanessa") that don't exist in Docker's Ubuntu repositories. Docker only supports Ubuntu codenames like "noble", "jammy", "focal".
**Solution:**
This issue has been resolved in HOPS v3.3.0+. The system now automatically detects the correct Ubuntu codename for Linux Mint installations using `UBUNTU_CODENAME` from `/etc/os-release`.
**Manual Fix (if needed):**
1. **Clean existing Docker repositories:**
```bash
sudo rm -f /etc/apt/sources.list.d/docker*
sudo rm -f /etc/apt/sources.list.d/*docker*
sudo rm -f /usr/share/keyrings/docker*
sudo rm -f /etc/apt/keyrings/docker*
sudo apt clean
```
2. **Verify Ubuntu codename detection:**
```bash
grep '^UBUNTU_CODENAME=' /etc/os-release
# Should return: UBUNTU_CODENAME=noble (for Linux Mint 22.x)
```
3. **Update HOPS to latest version:**
```bash
cd ~/hops
git pull
sudo ./hops --update
```
### Docker Installation Fails
**Symptoms:**
- `Package 'docker-ce' has no installation candidate`
- `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`
**Solutions:**
1. **Check Docker service status:**
```bash
sudo systemctl status docker
sudo systemctl status docker.socket
```
2. **Fix missing Docker group:**
```bash
sudo groupadd docker
sudo usermod -aG docker $USER
sudo chown root:docker /var/run/docker.sock
```
3. **Start Docker services:**
```bash
sudo systemctl start docker.socket
sudo systemctl start docker
sudo systemctl enable docker
```
4. **Verify Docker installation:**
```bash
sudo docker --version
sudo docker compose version
sudo docker info
```
## Directory and Permission Issues
### Homelab Directory Not Found
**Symptoms:**
```
ERROR: Homelab directory not found: /root/hops
```
**Root Cause:**
When running with `sudo`, the script may look for files in `/root/hops` instead of the user's home directory.
**Solution:**
This issue has been resolved in HOPS v3.3.0+. The system now properly detects the original user's home directory when running with sudo.
**Manual Workaround:**
```bash
# Ensure you're in the correct directory
cd ~/hops
sudo ./hops
sudo systemctl status docker
sudo systemctl restart docker
journalctl -u docker --since "1 hour ago"
```
### Permission Denied Errors
**Symptoms:**
- Permission denied accessing Docker socket
- Cannot create directories in `/opt/appdata`
**Solutions:**
1. **Fix Docker permissions:**
```bash
sudo usermod -aG docker $USER
# Log out and log back in, or run:
newgrp docker
```
2. **Fix directory permissions:**
```bash
sudo chown -R $USER:$USER ~/hops
sudo chmod -R 755 ~/hops
```
## Service Access Issues
### Cannot Access Service Web UI
**Symptoms:**
- Service shows as running but web UI is not accessible
- Connection refused errors
**Solutions:**
1. **Check container status:**
```bash
cd ~/hops
sudo docker compose ps
sudo docker compose logs [service-name]
```
2. **Verify port availability:**
```bash
sudo netstat -tlnp | grep :8989 # For Sonarr
sudo ss -tlnp | grep :8989 # Alternative command
```
3. **Check firewall settings:**
```bash
sudo ufw status
# If needed, allow ports:
sudo ufw allow 8989 # Example for Sonarr
```
4. **Restart services:**
```bash
cd ~/hops
sudo docker compose restart [service-name]
```
## Network Issues
### Docker Network Creation Fails
**Symptoms:**
- `Error response from daemon: network with name [network] already exists`
- Network connectivity issues between containers
**Solutions:**
1. **List existing networks:**
```bash
sudo docker network ls
```
2. **Remove conflicting networks:**
```bash
sudo docker network rm traefik homelab
```
3. **Recreate networks:**
```bash
cd ~/hops
sudo docker compose up -d
```
## System Requirements
### Insufficient Resources
**Symptoms:**
- Services randomly stopping
- Out of memory errors
- Slow performance
**Solutions:**
1. **Check system resources:**
```bash
free -h # Memory usage
df -h # Disk usage
top # CPU and memory usage
```
2. **Minimum requirements:**
- RAM: 2GB minimum, 4GB+ recommended
- Disk: 10GB minimum, 50GB+ recommended for media
- CPU: 2 cores minimum
3. **Optimize services:**
- Disable unnecessary services
- Adjust container resource limits
- Use external storage for media files
## Getting Help
### Log Files
Check HOPS log files for detailed error information:
**Linux:**
If Docker is missing or broken:
```bash
sudo tail -f /var/log/hops/hops-main-*.log
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
```
**macOS:**
## Linux Mint: Docker Repository Error
**Symptom:** `The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file`
Linux Mint uses its own codenames that Docker's repo doesn't recognise. HOPS
detects the underlying Ubuntu codename via `UBUNTU_CODENAME` in `/etc/os-release`.
Manual fix:
```bash
sudo tail -f /usr/local/var/log/hops/hops-main-*.log
sudo rm -f /etc/apt/sources.list.d/docker* /etc/apt/keyrings/docker*
sudo apt clean
grep '^UBUNTU_CODENAME=' /etc/os-release # confirm value is present
sudo ./hops # re-run installation
```
### Docker Compose Logs
## Permission Denied
```bash
# Docker socket access
sudo usermod -aG docker $USER
newgrp docker
# Directory ownership
sudo chown -R $USER:$USER ~/hops
sudo chown -R $USER:$USER /opt/appdata
```
## Service Won't Start
```bash
cd ~/hops
sudo docker compose logs -f [service-name]
docker compose logs [service-name]
docker compose ps
docker compose restart [service-name]
```
### System Information
When reporting issues, include:
## Port Already in Use
```bash
sudo lsof -i :[port]
sudo ss -tlnp | grep :[port]
```
## Cannot Access Service Web UI
1. Confirm container is running: `docker compose ps`
2. Check for port conflicts (above)
3. Check firewall: `sudo ufw status`
4. Allow port if needed: `sudo ufw allow [port]/tcp`
## Docker Network Errors
```bash
# Remove conflicting networks and recreate
sudo docker network rm traefik homelab
cd ~/hops && docker compose up -d
```
## Log Locations
- **HOPS logs**: `/var/log/hops/hops-main-*.log`
- **Service logs**: `docker compose logs [service-name]`
- **System logs**: `journalctl -u docker`
## Reporting Issues
Collect this info before reporting:
```bash
# System information
lsb_release -a
uname -a
docker --version
docker compose version
# HOPS version
./hops --version
# Container status
cd ~/hops && sudo docker compose ps
cd ~/hops && docker compose ps
```
### Reporting Issues
1. Check this troubleshooting guide first
2. Search existing [GitHub Issues](https://github.com/skiercm/hops/issues)
3. Create a new issue with:
- Complete error messages
- System information (above commands)
- Steps to reproduce
- Log file excerpts
## Recovery Commands
### Complete Reset
If HOPS installation is completely broken:
```bash
# Stop all containers
cd ~/hops && sudo docker compose down
# Remove containers and images (CAUTION: This removes all data)
sudo docker system prune -a --volumes
# Clean up repositories
sudo rm -f /etc/apt/sources.list.d/docker*
sudo apt clean
# Reinstall HOPS
cd ~/hops
git pull
sudo ./hops
```
### Partial Reset
To reset only HOPS configuration:
```bash
# Stop services
cd ~/hops && sudo docker compose down
# Remove generated files
rm -f ~/hops/docker-compose.yml ~/hops/.env
# Restart HOPS
sudo ./hops
```
---
## Version History
- **v3.3.0+**: Fixed Linux Mint Docker repository detection
- **v3.2.0+**: Added macOS support and improved error handling
- **v3.1.0+**: Initial multi-platform support
For the latest updates and fixes, always ensure you're running the latest version:
```bash
cd ~/hops
sudo ./hops --update
```
Report at: [git.canadabot.net/canadabot/hops/issues](https://git.canadabot.net/canadabot/hops/issues)