home-automation/DOCKER_GUIDE.md

Docker Guide für Home Automation

Vollständige Anleitung zum Ausführen aller Services mit Docker/finch.

Quick Start - Alle Services starten

Linux Server (empfohlen - mit Docker Network)

# 1. Images bauen
docker build -t api:dev -f apps/api/Dockerfile .
docker build -t ui:dev -f apps/ui/Dockerfile .
docker build -t abstraction:dev -f apps/abstraction/Dockerfile .
docker build -t simulator:dev -f apps/simulator/Dockerfile .

# 2. Netzwerk erstellen
docker network create home-automation

# 3. Abstraction Layer (MQTT Worker)
docker run -d --name abstraction \
  --network home-automation \
  -v $(pwd)/config:/app/config:ro \
  -e MQTT_BROKER=172.16.2.16 \
  -e REDIS_HOST=172.23.1.116 \
  -e REDIS_DB=8 \
  abstraction:dev

# 4. API Server
docker run -d --name api \
  --network home-automation \
  -p 8001:8001 \
  -v $(pwd)/config:/app/config:ro \
  -e MQTT_BROKER=172.16.2.16 \
  -e REDIS_HOST=172.23.1.116 \
  -e REDIS_DB=8 \
  api:dev

# 5. Web UI
docker run -d --name ui \
  --network home-automation \
  -p 8002:8002 \
  -e API_BASE=http://api:8001 \
  ui:dev

# 6. Device Simulator (optional)
docker run -d --name simulator \
  --network home-automation \
  -p 8010:8010 \
  -e MQTT_BROKER=172.16.2.16 \
  simulator:dev

macOS mit finch/nerdctl (Alternative)

# Images bauen (wie oben)

# Abstraction Layer
docker run -d --name abstraction \
  -v $(pwd)/config:/app/config:ro \
  -e MQTT_BROKER=172.16.2.16 \
  -e REDIS_HOST=172.23.1.116 \
  -e REDIS_DB=8 \
  abstraction:dev

# API Server
docker run -d --name api \
  -p 8001:8001 \
  -v $(pwd)/config:/app/config:ro \
  -e MQTT_BROKER=172.16.2.16 \
  -e REDIS_HOST=172.23.1.116 \
  -e REDIS_DB=8 \
  api:dev

# Web UI (mit host.docker.internal für macOS)
docker run -d --name ui \
  --add-host=host.docker.internal:host-gateway \
  -p 8002:8002 \
  -e API_BASE=http://host.docker.internal:8001 \
  ui:dev

# Device Simulator
docker run -d --name simulator \
  -p 8010:8010 \
  -e MQTT_BROKER=172.16.2.16 \
  simulator:dev

Zugriff

• Web UI: http://:8002
• API Docs: http://:8001/docs
• Simulator: http://:8010

Auf localhost: 127.0.0.1 oder localhost

finch/nerdctl Besonderheiten

Port-Binding Verhalten (nur macOS/Windows)

Standard Docker auf Linux:

• -p 8001:8001 → bindet auf 0.0.0.0:8001 (von überall erreichbar)

finch/nerdctl auf macOS:

• -p 8001:8001 → bindet auf 127.0.0.1:8001 (nur localhost)
• Dies ist ein Security-Feature von nerdctl
• Auf Linux-Servern ist das KEIN Problem!

Container-to-Container Kommunikation

Linux (empfohlen):

# Docker Network verwenden - Container sprechen sich mit Namen an
docker network create home-automation
docker run --network home-automation --name api ...
docker run --network home-automation -e API_BASE=http://api:8001 ui ...

macOS mit finch:

# host.docker.internal verwenden
docker run --add-host=host.docker.internal:host-gateway \
  -e API_BASE=http://host.docker.internal:8001 ui ...

Container verwalten

# Alle Container anzeigen
docker ps

# Logs anschauen
docker logs api
docker logs ui -f  # Follow mode

# Container stoppen
docker stop api ui abstraction simulator

# Container entfernen
docker rm api ui abstraction simulator

# Alles neu starten
docker stop api ui abstraction simulator && \
docker rm api ui abstraction simulator && \
# ... dann Quick Start Befehle von oben

Troubleshooting

UI zeigt "Keine Räume oder Geräte konfiguriert"

Problem: UI kann API nicht erreichen

Linux - Lösung:

# Verwende Docker Network
docker network create home-automation
docker stop ui && docker rm ui
docker run -d --name ui \
  --network home-automation \
  -p 8002:8002 \
  -e API_BASE=http://api:8001 \
  ui:dev

macOS/finch - Lösung:

docker stop ui && docker rm ui
docker run -d --name ui \
  --add-host=host.docker.internal:host-gateway \
  -p 8002:8002 \
  -e API_BASE=http://host.docker.internal:8001 \
  ui:dev

"Connection refused" in Logs

Check 1: Ist die API gestartet?

docker ps | grep api
curl http://127.0.0.1:8001/health

Check 2: Hat UI die richtige API_BASE?

docker inspect ui | grep API_BASE

Port bereits belegt

# Prüfe welcher Prozess Port 8001 nutzt
lsof -i :8001

# Oder mit netstat
netstat -an | grep 8001

# Alte Container aufräumen
docker ps -a | grep -E "api|ui|abstraction|simulator"
docker rm -f <container-id>

Produktiv-Deployment

Für Produktion auf Linux-Servern empfohlen:

1. Docker Compose (siehe infra/docker-compose.yml)
2. Docker Network für Service Discovery (siehe Linux Quick Start oben)
3. Volume Mounts für Persistenz
4. Health Checks in Kubernetes/Compose (nicht im Dockerfile)

Beispiel mit Docker Network (Linux)

# Netzwerk erstellen
docker network create home-automation

# Services starten (alle im gleichen Netzwerk)
docker run -d --name api --network home-automation \
  -p 8001:8001 \
  -v $(pwd)/config:/app/config:ro \
  api:dev

docker run -d --name ui --network home-automation \
  -p 8002:8002 \
  -e API_BASE=http://api:8001 \
  ui:dev

Vorteil: Service Discovery über Container-Namen, keine --add-host Tricks nötig.