229 lines
6.5 KiB
Markdown
229 lines
6.5 KiB
Markdown
# alan-agents-workstation
|
|
|
|
Docker-Setup fuer eine Arch-Linux-Workstation, damit **Hermes Agent** parallel zu **OpenClaw** laufen kann, ohne sich in die Quere zu kommen.
|
|
|
|
Wichtige Netzannahme in diesem Repo:
|
|
|
|
- **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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./scripts/alanctl status
|
|
```
|
|
|
|
### Logs
|
|
|
|
```bash
|
|
./scripts/alanctl logs
|
|
./scripts/alanctl logs dashboard
|
|
```
|
|
|
|
### Health / Diagnose
|
|
|
|
```bash
|
|
./scripts/alanctl doctor
|
|
```
|
|
|
|
### Backup
|
|
|
|
```bash
|
|
./scripts/alanctl backup
|
|
```
|
|
|
|
### Restore
|
|
|
|
```bash
|
|
./scripts/alanctl restore ./backups/hermes/hermes-YYYYMMDD-HHMMSS.tar.gz
|
|
```
|
|
|
|
### Update
|
|
|
|
Empfohlen: Hermes **nicht** auf `latest` lassen, sondern auf einen bewusst gesetzten Tag pinnen.
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./scripts/alanctl rollback-hermes
|
|
```
|
|
|
|
## Arch-Linux-Hinweise
|
|
|
|
Installiere mindestens:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./scripts/alanctl net-create-shim
|
|
```
|
|
|
|
Details dazu stehen in `docs/bridge-br0.md`.
|
|
|
|
## Verzeichnisstruktur
|
|
|
|
```text
|
|
.
|
|
├── 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`.
|