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