docs: README.md + CONTRIB.md ergaenzt (Mesh-Setup, Aenderungsregeln, Review-Korrekturen)
This commit is contained in:
Master-Bot
+78
@@ -0,0 +1,78 @@
|
||||
# CONTRIB.md — Regeln für Änderungen am Mesh
|
||||
|
||||
Verbindlich für Master **und** alle Sub-Agenten. Abgeleitet aus den
|
||||
Betriebsvorgaben des Betreibers (Stand 2026-10-08).
|
||||
|
||||
## 1. Grundsatz: ein Fix pro Schritt
|
||||
|
||||
- **Eine** Änderung, dann **testen**, dann die nächste. Keine Sammeländerungen.
|
||||
- Jede Änderung wird einzeln nachgewiesen (Messwert, HTTP-Code, Programmausgabe).
|
||||
- Die Messung muss zur Aussage passen: Bei Pipelines den Exitcode des
|
||||
**Scripts** messen, nicht den des letzten Pipe-Glieds (`| tail` liefert sonst
|
||||
immer 0).
|
||||
|
||||
## 2. Backup und Rollback
|
||||
|
||||
- Vor **jeder** Änderung ein Backup mit Datum im Dateinamen:
|
||||
`cp -p <datei> <datei>.bak-JJJJMMTT-HHMMSS`
|
||||
- Der **Rollback-Weg** wird im Kopf der geänderten Datei als Kommentar notiert
|
||||
und im Abschlussbericht genannt.
|
||||
- Keine Löschung von Daten, Prozessen oder Konfigurationen ohne Backup.
|
||||
- Beim Editieren von Dateien per Werkzeug **Eigentümer und Rechte danach prüfen**.
|
||||
Beispiel: `/var/spool/cron/crontabs/root` muss `root:crontab 600` bleiben —
|
||||
ein Editor kann die Gruppe auf `root` zurücksetzen und die crontab damit
|
||||
unbrauchbar machen.
|
||||
|
||||
## 3. Selbstcheck vor dem Einsatz
|
||||
|
||||
1. Syntax: `bash -n <script>` bzw. `python3 -m py_compile <script>`
|
||||
2. Dry-Run / Testlauf mit **erwartetem** Ergebnis (Negativfall einschliessen:
|
||||
Was passiert bei fehlender Datei, fehlendem Key, ungültiger Eingabe?)
|
||||
3. Code danach noch einmal vollständig lesen
|
||||
4. Erst dann produktiv einsetzen
|
||||
5. **Passenden Interpreter verwenden.** Der Agenten-PATH stellt Hermes' Python 3.14
|
||||
voran (ohne `yaml`), Cron nutzt `/usr/bin/python3` (3.12, mit `yaml`). Scripts, die
|
||||
im Cron laufen, deshalb **explizit mit `/usr/bin/python3`** starten — und zum Testen
|
||||
denselben Interpreter nehmen. Sonst entsteht ein Fehler, den es im Cron gar nicht gibt.
|
||||
|
||||
## 4. Infrastruktur-Regeln
|
||||
|
||||
- **Task-Austausch nur über NFS.** Samba/CIFS ist blockiert.
|
||||
- **SSH ausschliesslich key-basiert** und nur innerhalb des ZeroTier-Netzes.
|
||||
Kein Passwort-Fallback: `-o BatchMode=yes -o NumberOfPasswordPrompts=0`
|
||||
zusammen mit `-o IdentitiesOnly=yes` verhindert endlose Fehlversuche.
|
||||
Jeder Host nutzt **seinen eigenen** Key — kein Default, der auf einen fremden
|
||||
Key zeigt. Fehlt der Key, bricht das Script mit klarer Meldung ab.
|
||||
- **Keine Sicherheitseinstellungen ändern**, um einen Fehler zu umgehen
|
||||
(fail2ban, Ignore-Listen, Dateirechte).
|
||||
- Der Master bedient ein Host-Gateway für alle Profile; **lokale Gateways auf
|
||||
Sub-Agenten nicht ohne Abstimmung** zusätzlich starten (Doppelversorgung).
|
||||
|
||||
## 5. Budget
|
||||
|
||||
- Hartes Tageslimit **1 USD pro Agent**; Überschreitungen vermeiden, Arbeit
|
||||
lieber verschieben.
|
||||
- Bei Guthaben 0 stoppen die Sub-Agenten automatisch.
|
||||
- Modelle nur aus dem freigegebenen Satz in `/srv/work/costs/budget.yaml`
|
||||
(`modelle.erlaubt`). Abweichungen werden **gemeldet**, nicht eigenständig
|
||||
umgestellt.
|
||||
|
||||
## 6. Code-Änderungen
|
||||
|
||||
- Vor Code-Änderungen an Web-/Projekt-Repos: Review durch einen Sub-Agenten
|
||||
(Diff senden, Freigabe abwarten).
|
||||
- Pull/Push ohne Force. Bei Branch-Fehlern die **Ursache** angleichen
|
||||
(z. B. `git init -b main`), nicht erzwingen.
|
||||
|
||||
## 7. Grenzen ehrlich melden
|
||||
|
||||
Wenn ein Fix an fehlenden Rechten, einer Plattform-Sperre oder einer dieser
|
||||
Regeln scheitert: **nicht darum herum arbeiten.** Stattdessen stoppen, genau
|
||||
dokumentieren, wo die Grenze liegt, und ein bis zwei Optionen vorschlagen.
|
||||
Entschieden wird vom Betreiber.
|
||||
|
||||
## 8. Dokumentation
|
||||
|
||||
- Änderungen an Setup oder Ablauf: `README.md` und `CONTRIB.md` mitziehen.
|
||||
- Betriebsberichte als HTML auf `dokumentationen.perfekt-ohne-en.de` ablegen
|
||||
(eigener Dateiname — `index.html` wird minütlich vom Report überschrieben).
|
||||
@@ -0,0 +1,76 @@
|
||||
# mesh-configs — Konfigurations- und Service-Store des Hermes-Mesh
|
||||
|
||||
Dieses Repository ist der **versionierte Konfigurationsspeicher** des Mesh.
|
||||
Es wird vom Master (VPSHermes) automatisch gesichert (Cron: alle 6 h `git add -A`
|
||||
→ Commit → Push nach Gitea `mehlzoerwer/mesh-configs`).
|
||||
|
||||
## Inhalt
|
||||
|
||||
| Pfad | Inhalt |
|
||||
|---|---|
|
||||
| `config.yaml` | Hermes-Konfiguration des Masters |
|
||||
| `app.py` | Hilfsanwendung im Wurzelverzeichnis (wird mitgesichert) |
|
||||
| `cron/` | Cron-Jobs und deren Output-Historie |
|
||||
| `mesh-services/` | `docker-compose.yml` (Gitea + ntfy), `docker-compose.monitoring.yml` (Monitoring) |
|
||||
| `sites-available/` | nginx-VHost-Vorlagen |
|
||||
| `scripts/update_mesh.sh` | Fleet-Update-Helfer |
|
||||
| `skills/` | Spiegel der Skill-Bibliothek |
|
||||
|
||||
**Nicht** in diesem Repo: die operativen Betriebsskripte. Sie liegen direkt im
|
||||
Dateisystem (siehe unten) und werden hier nur dokumentiert.
|
||||
|
||||
## Mesh-Topologie
|
||||
|
||||
| Knoten | ZeroTier-IP | Rolle | Betriebsskripte |
|
||||
|---|---|---|---|
|
||||
| VPSHermes (Master) | 172.24.196.119 | Orchestrator + Deployer | `/usr/local/bin/mesh-*.{sh,py}` |
|
||||
| UnraidHermes | 172.24.34.142 | Entwickler | `~/.local/bin/mesh-*` |
|
||||
| SwitchHermes | 172.24.20.26 | Cockpit (ARM64) | `~/.local/bin/mesh-*` |
|
||||
| LaptopHermes | 172.24.178.202 | Worker (RTX 2060) | `~/.local/bin/mesh-*` |
|
||||
|
||||
Netz: ein ZeroTier-Netz `6ab565387a75e498` (172.24.0.0/16). Kein öffentlicher
|
||||
Zugang, kein Drittanbieter-Sync.
|
||||
|
||||
## Task-Austausch
|
||||
|
||||
- Gemeinsamer Ordner: `/srv/work/tasks/` — **ausschliesslich über NFS**
|
||||
(Samba/CIFS ist blockiert).
|
||||
- Ablauf: `offen/` → `in_arbeit/` (atomarer `mv`-Lock) → `fertig/`
|
||||
→ bei Bedarf `bugfix/` → `archiv/`.
|
||||
- Dateiname: `JJJJMMTT.<C>.<D>.<Auftrag>.json`, wobei `C.D` die letzten beiden
|
||||
Oktette der Ziel-IP sind (z. B. `20261008.34.142.ModelAssignment.json`).
|
||||
- Der Sub-Agent-Poller (`mesh-agent-poller.sh`, getaktet vom
|
||||
`mesh-poller-daemon.sh` alle 10 s) zieht Tasks per SSH/scp vom Master.
|
||||
|
||||
## Kosten und Budget
|
||||
|
||||
- Hartes Tageslimit: **1 USD pro Agent**; zusätzlich Guthaben-Stopp bei 0.
|
||||
- Zeitreihe: `/srv/work/costs/costs.jsonl`
|
||||
- Tagesverbrauch: `/srv/work/costs/daily.jsonl`
|
||||
- Monatssumme: `/srv/work/costs/month.json`
|
||||
- Bremse (Kill-Switch): `/srv/work/costs/kill_switches.json`,
|
||||
Logik in `mesh-cost-break.py`, Limits in `budget.yaml`.
|
||||
- Cron-Kette stündlich: `mesh-cost-track.sh` → `mesh-cost-break.py` → `mesh-cost-month.py`
|
||||
(immer mit `/usr/bin/python3` starten, siehe CONTRIB.md).
|
||||
|
||||
## Logs (Master)
|
||||
|
||||
| Log | Quelle |
|
||||
|---|---|
|
||||
| `/var/log/mesh-doku.log` | `mesh-master-report.sh` (Doku-Website) |
|
||||
| `/var/log/mesh-poller.log` | `mesh-master-poller.sh` (Ausfall-Fallback) |
|
||||
| `/var/log/mesh-cost.log` | Kosten-Kette |
|
||||
| `/var/log/mesh-budget-watch.log` | `mesh-budget-watch.sh` (Guthaben alle 30 min) |
|
||||
| `/var/log/wissensbasis-sync.log` | Wissensbasis- und Session-Archiv-Sync |
|
||||
|
||||
## Websites des Mesh
|
||||
|
||||
- `dokumentationen.perfekt-ohne-en.de` — Live-Panel (nginx-Root
|
||||
`/var/www/dokumentationen.perfekt-ohne-en.de`, **kleingeschrieben**)
|
||||
- `archiv.perfekt-ohne-en.de` — Tagesarchiv
|
||||
- `kanban.perfekt-ohne-en.de` — Aufgabenboard
|
||||
|
||||
## Bekannte Betriebsregeln
|
||||
|
||||
Siehe `CONTRIB.md`. Kurzfassung: ein Fix pro Schritt, Backup mit Datum,
|
||||
Rollback-Weg notieren, jedes Script vor dem Einsatz syntaktisch prüfen.
|
||||
Reference in New Issue
Block a user