Internetzugang fuer Hermes laeuft ueber dein br0.
Dafuer haengt Hermes an einem externen Docker-Macvlan-Netz, das auf dem Host-Bridge-Interface br0 basiert.
OpenClaw bleibt ein separater Stack mit eigenen Ports, Volumes und idealerweise demselben Uplink-Prinzip.

Der Fokus liegt auf:

saubere Trennung von Ports, Volumes und Netzwerken
resilientes Compose-Setup
komfortabler Workflow ueber alanctl
einfache Ablage in einem Gitea-Repo
explizite Beruecksichtigung von br0

Was dieses Repo liefert

compose.yaml fuer Hermes Gateway und optionales Dashboard
Wrapper-Skript scripts/alanctl
Backup/Restore/Update/Rollback-Workflow
Doku fuer Architektur, br0, Betrieb und Gitea-Import
systemd-User-Unit als Vorlage
Beispiel fuer getrennte OpenClaw-Integration

Schnellstart

cp .env.example .env
# .env an dein LAN anpassen: BR0_SUBNET, BR0_GATEWAY, BR0_IP_RANGE
./scripts/alanctl bootstrap
./scripts/alanctl net-create-br0
./scripts/alanctl init-hermes
./scripts/alanctl up

Optional mit Dashboard:

./scripts/alanctl up --dashboard

Danach:

Hermes Health/API lokal: http://127.0.0.1:18642/health
Hermes Dashboard lokal: http://127.0.0.1:19119

Langfristige Repo-Pflege in Gitea

Neu fuer den laufenden Betrieb:

CHANGELOG.md fuer nachvollziehbare Aenderungen
CONTRIBUTING.md fuer Arbeitsregeln
docs/release-process.md fuer Tags und Release Notes
docs/release-template.md als kopierbare Vorlage fuer Gitea-Releases
docs/upgrade-policy.md fuer Upgrade-Klassen und Rollback-Regeln
docs/maintenance.md fuer wiederkehrende Pflege
.gitea/ISSUE_TEMPLATE/* und .gitea/pull_request_template.md
.gitea/workflows/repo-check.yml fuer einfache Repo-Pruefungen
scripts/release-check und scripts/new-release
.editorconfig fuer konsistente Formatierung
CODEOWNERS und docs/maintainers.md fuer Review-Zustaendigkeiten

Release-Vorbereitung:

./scripts/release-check
./scripts/new-release 0.1.1

Warum zwei Netzebenen?

br0_uplink: externer Uplink fuer Internet/LAN via br0
hermes_private: internes Compose-Netz fuer saubere Service-Kommunikation
alan_agents_shared: optionales Querverbindungsnetz nur bei echtem Bedarf

So bekommt Hermes den Internetzugang ueber br0, waehrend API und Dashboard lokal auf 127.0.0.1 gebunden bleiben.

Workflow

Status

./scripts/alanctl status

Logs

./scripts/alanctl logs
./scripts/alanctl logs dashboard

Health / Diagnose

./scripts/alanctl doctor

Backup

./scripts/alanctl backup

Restore

./scripts/alanctl restore ./backups/hermes/hermes-YYYYMMDD-HHMMSS.tar.gz

Update

Empfohlen: Hermes nicht auf latest lassen, sondern auf einen bewusst gesetzten Tag pinnen.

./scripts/alanctl pin-hermes stable
./scripts/alanctl update-hermes           # aktualisiert auf den aktuell gepinnten Tag
./scripts/alanctl update-hermes v0.9.3    # gezieltes Upgrade auf einen bestimmten Tag

Rollback bei Bedarf:

./scripts/alanctl rollback-hermes

Arch-Linux-Hinweise

Installiere mindestens:

sudo pacman -S docker docker-compose curl iproute2
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
newgrp docker

Fuer den optionalen Host-Shim brauchst du sudo fuer ip link und ip route.

Wichtige Macvlan-Einschraenkung

Bei Docker-Macvlan koennen Host und Container nicht direkt miteinander sprechen, solange du keinen Host-Shim anlegst.

Wenn du das brauchst, z. B. fuer lokale Tests vom Host auf die br0-IP des Containers:

./scripts/alanctl net-create-shim

Details dazu stehen in docs/bridge-br0.md.

Verzeichnisstruktur

.
├── compose
│   └── openclaw.override.example.yaml
├── compose.yaml
├── docs
│   ├── architecture.md
│   ├── bridge-br0.md
│   ├── gitea-import.md
│   ├── hermes.md
│   ├── maintenance.md
│   ├── openclaw-coexistence.md
│   ├── release-process.md
│   └── upgrade-policy.md
├── scripts
│   ├── alanctl
│   ├── new-release
│   └── release-check
├── state
│   └── hermes/
├── backups
│   └── hermes/
└── systemd
    └── user
        └── alan-hermes.service

Warum die Ports absichtlich ungewoehnlich sind

Die offiziellen Hermes-Beispiele verwenden hostseitig meist 8642 fuer die API und 9119 fuer das Dashboard. Dieses Repo mappt absichtlich auf 18642 und 19119, bindet sie aber nur an 127.0.0.1, damit ein bestehendes OpenClaw- oder sonstiges Dev-Setup auf der Workstation seltener kollidiert.

Maintainer und Review

.editorconfig sorgt fuer konsistente Grundformatierung in Editor und CI
CODEOWNERS beschreibt Default-Owner und Review-Schwerpunkte
docs/maintainers.md ist die betriebliche Fallback-Doku, falls deine Gitea-Instanz CODEOWNERS nicht automatisch auswertet

Lizenz und Security

LICENSE: MIT-Lizenz fuer klare Weitergabe und Anpassung
SECURITY.md: Richtlinie fuer Security-Meldungen und gepflegte Staende

Sicherheit und Betriebsgrenzen

Dieses Repo trennt Hermes und OpenClaw bewusst.
Nutze das Shared-Netz nur, wenn wirklich noetig.
Lege keine Secrets ins Git-Repo.
Wenn du OpenClaw separat betreibst, gib ihm andere Host-Ports und eigene Volumes.
Das br0-Uplink-Netz ist extern und wird absichtlich nicht blind bei docker compose up erzeugt.

Naechster sinnvoller Ausbau

Reverse-Proxy mit lokalem DNS-Namen
systemd-User-Integration aktivieren
Borg/Restic fuer Off-Host-Backups
eigene Profiles fuer mehrere Hermes-Instanzen
optional identisches br0-Uplink-Muster fuer OpenClaw

Update-Strategie

Dieses Repo ist bewusst so gebaut, dass Updates kontrolliert ablaufen:

HERMES_TAG wird in .env gepinnt
update-hermes erstellt zuerst ein Backup
danach wird das Ziel-Image gepullt und Hermes neu erstellt
der Healthcheck wird aktiv abgewartet
bei Fehlschlag wird automatisch auf den vorherigen Tag zurueckgestellt
der zuletzt erfolgreiche Stand wird in state/hermes/.last-known-good.env gespeichert

Fuer reproduzierbare Setups auf Workstation oder Homeserver ist das deutlich robuster als blindes Arbeiten mit latest.