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)

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