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>
96 lines
2.0 KiB
Markdown
96 lines
2.0 KiB
Markdown
# Troubleshooting
|
|
|
|
## Docker Not Starting
|
|
|
|
```bash
|
|
sudo systemctl status docker
|
|
sudo systemctl restart docker
|
|
journalctl -u docker --since "1 hour ago"
|
|
```
|
|
|
|
If Docker is missing or broken:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
|
|
```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
|
|
docker compose logs [service-name]
|
|
docker compose ps
|
|
docker compose restart [service-name]
|
|
```
|
|
|
|
## 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
|
|
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](https://git.canadabot.net/canadabot/hops/issues)
|