Stephen Klein
a7213441da
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>
2.0 KiB
2.0 KiB
Troubleshooting
Docker Not Starting
sudo systemctl status docker
sudo systemctl restart docker
journalctl -u docker --since "1 hour ago"
If Docker is missing or broken:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
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:
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
Permission Denied
# 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
cd ~/hops
docker compose logs [service-name]
docker compose ps
docker compose restart [service-name]
Port Already in Use
sudo lsof -i :[port]
sudo ss -tlnp | grep :[port]
Cannot Access Service Web UI
- Confirm container is running:
docker compose ps - Check for port conflicts (above)
- Check firewall:
sudo ufw status - Allow port if needed:
sudo ufw allow [port]/tcp
Docker Network Errors
# 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:
lsb_release -a
uname -a
docker --version
docker compose version
./hops --version
cd ~/hops && docker compose ps
Report at: git.canadabot.net/canadabot/hops/issues