301 lines
6.9 KiB
Markdown
301 lines
6.9 KiB
Markdown
# Docker Troubleshooting Guide for Hyprmonitors Home Assistant Integration
|
|
|
|
This guide helps resolve common networking issues when running Home Assistant in Docker containers and trying to connect to the Hyprmonitors daemon running on the host system.
|
|
|
|
## Quick Fix Summary
|
|
|
|
**TL;DR**: Replace `localhost` with `host.docker.internal` when configuring the integration in Home Assistant.
|
|
|
|
## The Problem
|
|
|
|
When Home Assistant runs inside a Docker container, `localhost` refers to the container's internal network, not the host system where your Hyprmonitors daemon is running. This causes connection timeouts and failures.
|
|
|
|
## Solutions
|
|
|
|
### Solution 1: Use Docker Host Alias (Recommended)
|
|
|
|
**For Docker Desktop (Windows/Mac):**
|
|
```
|
|
Host: host.docker.internal
|
|
Port: 3000
|
|
```
|
|
|
|
**For Docker on Linux:**
|
|
Add to your `docker-compose.yml`:
|
|
```yaml
|
|
services:
|
|
homeassistant:
|
|
# ... other config ...
|
|
extra_hosts:
|
|
- "host.docker.internal:host-gateway"
|
|
```
|
|
|
|
Or add to `docker run` command:
|
|
```bash
|
|
docker run --add-host=host.docker.internal:host-gateway ...
|
|
```
|
|
|
|
### Solution 2: Use Host Machine's IP Address
|
|
|
|
Find your host machine's IP address:
|
|
```bash
|
|
# Linux/Mac
|
|
hostname -I | awk '{print $1}'
|
|
# or
|
|
ip route get 8.8.8.8 | awk '{print $7}'
|
|
|
|
# Windows
|
|
ipconfig | findstr IPv4
|
|
```
|
|
|
|
Then use this IP in Home Assistant:
|
|
```
|
|
Host: 192.168.1.100 # Your actual IP
|
|
Port: 3000
|
|
```
|
|
|
|
### Solution 3: Host Network Mode
|
|
|
|
Run Home Assistant with host networking (Linux only):
|
|
```bash
|
|
docker run --network host ...
|
|
```
|
|
|
|
Or in `docker-compose.yml`:
|
|
```yaml
|
|
services:
|
|
homeassistant:
|
|
network_mode: host
|
|
# Remove ports section when using host mode
|
|
```
|
|
|
|
## Testing Connectivity
|
|
|
|
### Step 1: Run the Connectivity Test
|
|
|
|
From the `hyprmonitors/homeassistant` directory:
|
|
|
|
```bash
|
|
# Test default localhost (will likely fail in Docker)
|
|
python3 test_connectivity.py
|
|
|
|
# Test Docker host alias
|
|
python3 test_connectivity.py host.docker.internal 3000
|
|
|
|
# Test specific IP
|
|
python3 test_connectivity.py 192.168.1.100 3000
|
|
```
|
|
|
|
### Step 2: Test from Inside Home Assistant Container
|
|
|
|
```bash
|
|
# Get into the HA container
|
|
docker exec -it homeassistant bash
|
|
|
|
# Test connectivity
|
|
curl http://host.docker.internal:3000/health
|
|
# or
|
|
curl http://192.168.1.100:3000/health
|
|
```
|
|
|
|
Expected response:
|
|
```json
|
|
{"success":true,"message":"Hyprland Monitor Control Server is running","monitor":null}
|
|
```
|
|
|
|
## Common Docker Configurations
|
|
|
|
### Docker Compose Example
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
|
|
services:
|
|
homeassistant:
|
|
container_name: homeassistant
|
|
image: ghcr.io/home-assistant/home-assistant:stable
|
|
volumes:
|
|
- ./config:/config
|
|
- /etc/localtime:/etc/localtime:ro
|
|
environment:
|
|
- TZ=America/New_York
|
|
ports:
|
|
- "8123:8123"
|
|
restart: unless-stopped
|
|
extra_hosts:
|
|
- "host.docker.internal:host-gateway" # Linux
|
|
# For Windows/Mac, this is automatic
|
|
```
|
|
|
|
### Docker Run Example
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name homeassistant \
|
|
--privileged \
|
|
--restart=unless-stopped \
|
|
-e TZ=America/New_York \
|
|
-v /home/user/homeassistant:/config \
|
|
-v /etc/localtime:/etc/localtime:ro \
|
|
--add-host=host.docker.internal:host-gateway \
|
|
-p 8123:8123 \
|
|
ghcr.io/home-assistant/home-assistant:stable
|
|
```
|
|
|
|
## Firewall Configuration
|
|
|
|
Make sure port 3000 is accessible from Docker containers:
|
|
|
|
### UFW (Ubuntu)
|
|
```bash
|
|
sudo ufw allow 3000
|
|
```
|
|
|
|
### iptables
|
|
```bash
|
|
# Allow Docker containers to access host port 3000
|
|
sudo iptables -A INPUT -i docker0 -p tcp --dport 3000 -j ACCEPT
|
|
```
|
|
|
|
### firewalld (RHEL/CentOS)
|
|
```bash
|
|
sudo firewall-cmd --permanent --add-port=3000/tcp
|
|
sudo firewall-cmd --reload
|
|
```
|
|
|
|
## Troubleshooting Steps
|
|
|
|
### 1. Verify Hyprmonitors is Running
|
|
```bash
|
|
# Check if service is running
|
|
systemctl --user status hyprmonitors
|
|
|
|
# Check if port is listening
|
|
ss -tlnp | grep :3000
|
|
|
|
# Test locally on host
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
### 2. Check Docker Network
|
|
```bash
|
|
# See Docker networks
|
|
docker network ls
|
|
|
|
# Inspect Home Assistant container network
|
|
docker inspect homeassistant | grep -A 20 NetworkSettings
|
|
```
|
|
|
|
### 3. Debug Container DNS
|
|
```bash
|
|
# From inside HA container
|
|
docker exec -it homeassistant bash
|
|
|
|
# Test DNS resolution
|
|
nslookup host.docker.internal
|
|
|
|
# Test network connectivity
|
|
ping host.docker.internal
|
|
|
|
# Check what localhost resolves to
|
|
ping localhost # Should be 127.0.0.1 (container internal)
|
|
```
|
|
|
|
### 4. Check Home Assistant Logs
|
|
```bash
|
|
# View HA logs for connection errors
|
|
docker logs homeassistant | grep hyprmonitors
|
|
|
|
# Enable debug logging in Home Assistant configuration.yaml:
|
|
# logger:
|
|
# default: info
|
|
# logs:
|
|
# custom_components.hyprmonitors: debug
|
|
```
|
|
|
|
## Platform-Specific Notes
|
|
|
|
### Docker Desktop (Windows/Mac)
|
|
- `host.docker.internal` works automatically
|
|
- No extra configuration needed
|
|
- Gateway IP is handled transparently
|
|
|
|
### Docker Engine (Linux)
|
|
- Must add `--add-host=host.docker.internal:host-gateway`
|
|
- Or use actual host IP address
|
|
- Gateway IP varies by Docker version
|
|
|
|
### Podman
|
|
- Use `host.containers.internal` instead of `host.docker.internal`
|
|
- May need `--add-host=host.containers.internal:host-gateway`
|
|
|
|
## Alternative Solutions
|
|
|
|
### 1. Run Hyprmonitors in Container
|
|
Create a Dockerfile for Hyprmonitors and run it in the same Docker network as Home Assistant.
|
|
|
|
### 2. Use Docker Bridge Network
|
|
Create a custom bridge network and connect both containers.
|
|
|
|
### 3. Use Docker Secrets/Configs
|
|
Store connection details in Docker secrets for better security.
|
|
|
|
## Error Messages Reference
|
|
|
|
### "Connection timed out"
|
|
- **Cause**: Cannot reach the host from container
|
|
- **Solution**: Use `host.docker.internal` or host IP
|
|
|
|
### "Connection refused"
|
|
- **Cause**: Service not running or wrong port
|
|
- **Solution**: Check if Hyprmonitors daemon is running
|
|
|
|
### "Name or service not known"
|
|
- **Cause**: DNS resolution failure
|
|
- **Solution**: Use IP address instead of hostname
|
|
|
|
### "No route to host"
|
|
- **Cause**: Network/firewall blocking connection
|
|
- **Solution**: Check firewall rules and Docker network config
|
|
|
|
## Getting Help
|
|
|
|
If you're still having issues:
|
|
|
|
1. Run the connectivity test: `python3 test_connectivity.py`
|
|
2. Check Home Assistant logs for detailed error messages
|
|
3. Verify your Docker configuration matches the examples above
|
|
4. Test the connection manually using curl from inside the container
|
|
|
|
## Example Working Configuration
|
|
|
|
Here's a complete working example:
|
|
|
|
**docker-compose.yml:**
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
homeassistant:
|
|
container_name: homeassistant
|
|
image: ghcr.io/home-assistant/home-assistant:stable
|
|
volumes:
|
|
- ./config:/config
|
|
ports:
|
|
- "8123:8123"
|
|
extra_hosts:
|
|
- "host.docker.internal:host-gateway"
|
|
restart: unless-stopped
|
|
```
|
|
|
|
**Home Assistant Integration Config:**
|
|
```
|
|
Host: host.docker.internal
|
|
Port: 3000
|
|
```
|
|
|
|
**Test Command:**
|
|
```bash
|
|
docker exec -it homeassistant curl http://host.docker.internal:3000/health
|
|
```
|
|
|
|
This configuration should work in most Docker setups and resolve the networking issues between Home Assistant and your Hyprmonitors daemon. |