Initial version of the Hermes self learning agent setup of JR IT Services.
This commit is contained in:
@@ -0,0 +1,228 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user