canadabot/hops
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive troubleshooting documentation and update summary

Browse Source 
- Update summary7-19.txt with complete resolution of Linux Mint Docker issue
- Add TROUBLESHOOTING.md with detailed solutions for common HOPS issues
- Document the critical case sensitivity bug fix (LinuxMint vs Linuxmint)
- Provide manual fixes for Docker service and directory detection issues
- Include recovery commands and system requirements

This resolves the Linux Mint repository detection issue completely.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Stephen Klein
2025-07-20 08:22:13 -04:00
parent a28a6e5007
commit 2ba24f2a94
2 changed files with 405 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TROUBLESHOOTING.md
+314
View File
@@ -0,0 +1,314 @@
# HOPS Troubleshooting Guide
This document provides solutions to common issues encountered when installing and running HOPS.
## 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
```
### 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:**
```bash
sudo tail -f /var/log/hops/hops-main-*.log
```
**macOS:**
```bash
sudo tail -f /usr/local/var/log/hops/hops-main-*.log
```
### Docker Compose Logs
```bash
cd ~/hops
sudo docker compose logs -f [service-name]
```
### System Information
When reporting issues, include:
```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
```
### 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
```
summary7-19.txt
+91 -16
View File
@@ -65,31 +65,106 @@ ubuntu_codename=$(grep '^UBUNTU_CODENAME=' /etc/os-release | cut -d= -f2)
- This is the correct Ubuntu codename that Docker repositories support - This is the correct Ubuntu codename that Docker repositories support
- Should eliminate need for manual version mapping - Should eliminate need for manual version mapping
### Current Status #### 5. Root Cause Discovery - Wrong Installation Path (Session 2)
- Two commits pushed to fix the issue **Date:** July 19, 2025 (Evening)
- System cleanup performed on Linux Mint machine **Discovery:** User was running `./setup` script, but fixes were applied to different code paths
- Error persists despite fixes **Investigation Steps:**
- User is updating Linux Mint system and rebooting before next test - Confirmed user had latest code with fixes (commit 4fd78ec)
- System was completely clean of Docker repositories
- `UBUNTU_CODENAME=noble` correctly detected
- Still getting "xia" error despite fixes
### Next Steps **Key Finding:** The `setup` script uses `lib/system.sh::install_docker()` which was calling Docker's convenience script `curl -fsSL https://get.docker.com | sh`, NOT the fixed installation functions in `privileged-setup` or `lib/privileges.sh`.
1. Test HOPS installation after Linux Mint system updates and reboot
2. If issue persists, investigate: #### 6. Fix Applied to Correct Installation Path (Commit ce0f7f2)
- Whether updated code is actually being executed **Files Modified:** `lib/system.sh` (lines 1122-1168)
- Alternative installation paths being used **Approach:**
- System-level caching preventing fix from taking effect - Replaced Docker convenience script with manual repository setup
3. Consider manual repository configuration as verification step - Added Linux Mint Ubuntu codename detection logic to `lib/system.sh`
4. Update changelog if fix is successful - Included same UBUNTU_CODENAME detection and fallback mapping
- Added debug output: "Using Ubuntu codename: X for Docker repository"
**Result:** User tested after pulling latest code - still experiencing same "xia" error
### Current Status (End of Session 2)
**Problem State:** Persistent "xia" repository error despite comprehensive fixes
**Fixes Applied:**
- Three different installation paths updated with Linux Mint detection
- Complete Docker repository cleanup performed multiple times
- Debug output added to track codename detection
- Manual testing confirmed UBUNTU_CODENAME=noble is available
**Unresolved Questions:**
1. Why debug output from fixed code is not appearing in installation logs
2. Whether there's a fourth Docker installation path not yet discovered
3. Possible system-level caching or existing Docker installation interfering
4. Whether the correct script path is actually being executed
### Next Steps (For Tomorrow)
1. **Execution Path Verification:** Add debug traces to determine which exact functions are being called during `./setup`
2. **Docker Installation Check:** Verify if Docker is already installed and causing early function returns
3. **Complete Docker Removal:** If Docker exists, completely remove it before testing fixes
4. **Alternative Installation Methods:** Test other entry points (`./hops`, `./install`, `./privileged-setup` directly)
5. **System State Analysis:** Check for any persistent apt configurations or cached repository information
### Technical Notes ### Technical Notes
- Linux Mint consistently provides `UBUNTU_CODENAME` in modern versions - Linux Mint consistently provides `UBUNTU_CODENAME` in modern versions
- Using this field is more reliable than version-based mapping - Using this field is more reliable than version-based mapping
- Docker installation uses Ubuntu repositories for Debian-based distributions - Docker installation uses Ubuntu repositories for Debian-based distributions
- Issue affects all Linux Mint installations using HOPS - Issue affects all Linux Mint installations using HOPS
- The Docker convenience script `get.docker.com` has its own broken Linux Mint detection
### Files Modified ### Files Modified
- `privileged-setup` (lines 43-70) - `privileged-setup` (lines 43-70, 72) - ✅ Fixed
- `lib/privileges.sh` (lines 199-226) - `lib/privileges.sh` (lines 199-226, 228) - ✅ Fixed
- `lib/system.sh` (lines 1122-1168) - ✅ Fixed
#### 7. Final Resolution (Session 3 - July 20, 2025)
**Root Cause Identified:** Critical case sensitivity bug in Linux Mint detection
- `lsb_release -is` returns `"Linuxmint"` (lowercase 'm')
- All code was checking for `"LinuxMint"` (uppercase 'M')
- This caused Linux Mint detection to fail completely, falling back to "xia" codename
**Final Fixes Applied:**
1. **Case Sensitivity Fix (Commit 736ed1b):**
- Fixed `lib/system.sh:1151`: `"LinuxMint"` → `"Linuxmint"`
- Fixed `privileged-setup:45`: `"LinuxMint"` → `"Linuxmint"`
- Fixed `lib/privileges.sh:201`: `"LinuxMint"` → `"Linuxmint"`
2. **Debug Tracing Added (Commit d2e9a69):**
- Added comprehensive debug output to trace execution paths
- Fixed Docker repository cleanup order in `remove_docker_linux()`
- Added specific cleanup for Linux Mint codenames (xia, vera, vanessa)
3. **Docker Service Issues (Manual Fix):**
- Created missing `docker` group: `sudo groupadd docker`
- Added user to docker group: `sudo usermod -aG docker skier`
- Started Docker services: `sudo systemctl start docker.socket docker`
4. **Directory Detection Fix (Commit a28a6e5):**
- Fixed sudo home directory resolution in `install` script
- Changed `$HOME/hops` to use `$SUDO_USER` home directory
- Resolved `/root/hops` vs `/home/skier/hops` issue
**Final Result:** ✅ **COMPLETE SUCCESS**
- Docker repositories now use correct Ubuntu codename "noble"
- Sonarr container deployed and running successfully
- Web UI accessible at localhost:8989
- All Linux Mint Docker repository issues resolved
### Current Status (RESOLVED)
**Problem State:** ✅ **COMPLETELY RESOLVED**
**Final Working State:**
- Linux Mint detection working: `DEBUG: Linux Mint detected, checking for UBUNTU_CODENAME`
- Ubuntu codename detection: `DEBUG: Found UBUNTU_CODENAME=noble in /etc/os-release`
- Repository configuration: `ℹ️ Using Ubuntu codename: noble for Docker repository`
- Docker installation: Downloads from `https://download.docker.com/linux/ubuntu noble`
- Service deployment: Sonarr running and accessible
### Git Commits ### Git Commits
- `af57a77`: Initial Linux Mint version mapping fix - `af57a77`: Initial Linux Mint version mapping fix
- `4fd78ec`: Improved fix using UBUNTU_CODENAME detection - `4fd78ec`: Improved fix using UBUNTU_CODENAME detection
- `ce0f7f2`: Fix lib/system.sh Docker installation path with manual repository setup
- `d2e9a69`: Fix Docker repository issues with debug tracing and cleanup order
- `736ed1b`: Fix critical Linux Mint case sensitivity bug in repository detection
- `a28a6e5`: Fix homelab directory detection when running with sudo