Initial version of the Hermes self learning agent setup of JR IT Services.

docs/bridge-br0.md

@@ -0,0 +1,66 @@
+# Betrieb ueber `br0`
+
+## Warum hier Macvlan verwendet wird
+
+Du hast vorgegeben, dass der Container **ueber deine Bridge `br0`** laufen soll, wenn Internetzugang benoetigt wird.
+
+Fuer Docker auf Linux ist das sauberste Muster dafuer in der Regel ein **externes Macvlan-Netz** mit:
+
+- Parent: `br0`
+- eigenem IP-Bereich fuer Container
+- optionaler statischer IP pro Service
+
+## Was du in `.env` anpassen musst
+
+Mindestens:
+
+```dotenv
+BR0_PARENT=br0
+BR0_SUBNET=192.168.10.0/24
+BR0_GATEWAY=192.168.10.1
+BR0_IP_RANGE=192.168.10.224/28
+BR0_DOCKER_NETWORK=br0_lan
+```
+
+Optional:
+
+```dotenv
+BR0_HOST_SHIM_CIDR=192.168.10.239/32
+```
+
+Nimm fuer `BR0_IP_RANGE` am besten einen kleinen Bereich, der **nicht** durch DHCP an normale Clients vergeben wird.
+
+## Externes Docker-Netz anlegen
+
+```bash
+./scripts/alanctl net-create-br0
+```
+
+Das erzeugt ein Docker-Macvlan-Netz auf `br0`.
+
+## Bekannte Einschraenkung: Host <-> Container
+
+Bei Macvlan koennen Host und Container standardmaessig **nicht direkt miteinander sprechen**. Das ist kein Fehler in deinem Compose-Setup, sondern normales Macvlan-Verhalten.
+
+### Loesung: Host-Shim anlegen
+
+```bash
+./scripts/alanctl net-create-shim
+```
+
+Das erzeugt auf dem Host ein zusaetzliches Macvlan-Interface und routet den konfigurierten IP-Bereich dorthin.
+
+## Wann du den Shim wirklich brauchst
+
+- du willst den Container auf seiner `br0`-IP direkt vom Host anpingen
+- du willst vom Host Dienste auf der `br0`-IP ansprechen
+
+Wenn dir dagegen die lokal publizierten Ports `127.0.0.1:18642` und `127.0.0.1:19119` reichen, brauchst du den Shim oft gar nicht.
+
+## Empfehlung fuer parallelen OpenClaw-Betrieb
+
+- gleicher Parent `br0`
+- anderer Host-Port
+- anderer Volume-Pfad
+- eigene statische IP oder eigene Zuteilung aus demselben `BR0_IP_RANGE`
+- kein gemeinsames wildes Mounten von Host-Pfaden