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
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)