docs

2025-11-06 16:50:23 +01:00
parent b7efae61c4
commit 6bf8ac3f99
4 changed files with 278 additions and 1 deletions
--- a/DOCKER_GUIDE.md
+++ b/DOCKER_GUIDE.md
@@ -0,0 +1,230 @@
+# 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)
+
+```bash
+# 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)
+
+```bash
+# 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://<server-ip>:8002
+- **API Docs**: http://<server-ip>:8001/docs
+- **Simulator**: http://<server-ip>: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):**
+```bash
+# 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:**
+```bash
+# host.docker.internal verwenden
+docker run --add-host=host.docker.internal:host-gateway \
+  -e API_BASE=http://host.docker.internal:8001 ui ...
+```
+
+## Container verwalten
+
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+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?
+```bash
+docker ps | grep api
+curl http://127.0.0.1:8001/health
+```
+
+**Check 2:** Hat UI die richtige API_BASE?
+```bash
+docker inspect ui | grep API_BASE
+```
+
+### Port bereits belegt
+
+```bash
+# 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)
+
+```bash
+# 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.
--- a/apps/api/README.md
+++ b/apps/api/README.md
@@ -51,6 +51,23 @@ docker run --rm -p 8001:8001 \
  api:dev
 ```

+**Mit Docker Network (empfohlen für Linux):**
+```bash
+docker network create home-automation
+docker run --rm -p 8001:8001 \
+  --network home-automation \
+  --name api \
+  -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
+```
+
+**Hinweise:**
+- **Linux**: Port wird auf `0.0.0.0:8001` gebunden (von überall erreichbar)
+- **macOS/finch**: Port wird auf `127.0.0.1:8001` gebunden (nur localhost)
+
 #### Environment Variables

 | Variable | Default | Description |
--- a/apps/simulator/README.md
+++ b/apps/simulator/README.md
@@ -59,6 +59,16 @@ docker run --rm -p 8010:8010 \
  simulator:dev
 ```

+**Mit Docker Network (optional):**
+```bash
+docker network create home-automation
+docker run --rm -p 8010:8010 \
+  --network home-automation \
+  --name simulator \
+  -e MQTT_BROKER=172.16.2.16 \
+  simulator:dev
+```
+
 #### Environment Variables

 | Variable | Default | Description |
--- a/apps/ui/README.md
+++ b/apps/ui/README.md
@@ -37,14 +37,34 @@ docker build -t ui:dev -f apps/ui/Dockerfile .

 #### Run Container

+**Linux Server (empfohlen):**
 ```bash
+# Mit Docker Network für Container-to-Container Kommunikation
+docker network create home-automation
 docker run --rm -p 8002:8002 \
+  --network home-automation \
  -e UI_PORT=8002 \
-  -e API_BASE=http://localhost:8001 \
+  -e API_BASE=http://api:8001 \
  -e BASE_PATH=/ \
  ui:dev
 ```

+**macOS mit finch/nerdctl:**
+```bash
+docker run --rm -p 8002:8002 \
+  --add-host=host.docker.internal:host-gateway \
+  -e UI_PORT=8002 \
+  -e API_BASE=http://host.docker.internal:8001 \
+  -e BASE_PATH=/ \
+  ui:dev
+```
+
+**Hinweise:**
+- **Linux**: Verwende Docker Network und Service-Namen (`http://api:8001`)
+- **macOS/finch**: Verwende `host.docker.internal` mit `--add-host` flag
+- Die UI macht Server-Side API-Aufrufe beim Rendern der Seite
+- Browser-seitige Realtime-Updates (SSE) gehen direkt vom Browser zur API
+
 #### Environment Variables

 | Variable | Default | Description |