hyprmonitors/homeassistant/DOCKER_TROUBLESHOOTING.md

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:

services:
  homeassistant:
    # ... other config ...
    extra_hosts:
      - "host.docker.internal:host-gateway"

Or add to docker run command:

docker run --add-host=host.docker.internal:host-gateway ...

Solution 2: Use Host Machine's IP Address

Find your host machine's IP address:

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

docker run --network host ...

Or in docker-compose.yml:

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:

# 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

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

{"success":true,"message":"Hyprland Monitor Control Server is running","monitor":null}

Common Docker Configurations

Docker Compose Example

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

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)

sudo ufw allow 3000

iptables

# Allow Docker containers to access host port 3000
sudo iptables -A INPUT -i docker0 -p tcp --dport 3000 -j ACCEPT

firewalld (RHEL/CentOS)

sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

Troubleshooting Steps

1. Verify Hyprmonitors is Running

# 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

# See Docker networks
docker network ls

# Inspect Home Assistant container network
docker inspect homeassistant | grep -A 20 NetworkSettings

3. Debug Container DNS

# 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

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

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:

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.