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