feat: Added stuff

homeassistant/DOCKER_TROUBLESHOOTING.md

@@ -0,0 +1,301 @@
+# 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.