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