diff --git a/DOCKER_GUIDE.md b/DOCKER_GUIDE.md new file mode 100644 index 0000000..f00d286 --- /dev/null +++ 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://: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):** +```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 +``` + +## 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. diff --git a/apps/api/README.md b/apps/api/README.md index 5edff04..7f3d158 100644 --- 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 | diff --git a/apps/simulator/README.md b/apps/simulator/README.md index 4fd1147..89461f9 100644 --- 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 | diff --git a/apps/ui/README.md b/apps/ui/README.md index 3cb389b..ff0dd2c 100644 --- 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 |