Initial version of the Hermes self learning agent setup of JR IT Services.

2026-04-21 11:53:29 +02:00
commit 7f9b0e6c5f
31 changed files with 1966 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Upgrade-Policy
+
+## Grundsatz
+
+Upgrades sollen reversibel, dokumentiert und fuer eine einzelne Workstation realistisch bedienbar sein.
+
+## Klassen von Aenderungen
+
+### 1. Sicheres Patch-Upgrade
+
+Beispiele:
+- Doku-Updates
+- Healthcheck-Feinschliff
+- nicht-invasive Skriptkorrekturen
+
+Erwartung:
+- kein manueller Eingriff noetig
+- normales `update-hermes` reicht
+
+### 2. Operatives Minor-Upgrade
+
+Beispiele:
+- neue optionale Dienste
+- neue `.env`-Variablen mit Default
+- neue Docs/Tools
+
+Erwartung:
+- Release Notes lesen
+- `git diff .env.example` gegen lokale `.env` pruefen
+- ggf. neuen Key ergaenzen
+
+### 3. Breakendes Upgrade
+
+Beispiele:
+- Netzwerknamen aendern
+- Compose-Service-Namen aendern
+- persistente Pfade aendern
+- State-/Datenmigrationen mit Rueckwirkungsrisiko
+
+Erwartung:
+- Backup Pflicht
+- Upgrade-Fenster bewusst planen
+- Rollback testen
+- Release Notes muessen eine explizite Migrationsanleitung enthalten
+
+## Pflicht vor jedem geplanten Upgrade
+
+```bash
+./scripts/alanctl doctor
+./scripts/alanctl backup
+```
+
+## Pflicht bei Repo-Upgrade
+
+Wenn du das Repo selbst aktualisierst:
+
+```bash
+git fetch --tags
+git checkout <ziel-tag-oder-branch>
+./scripts/release-check
+```
+
+Danach erst:
+
+```bash
+./scripts/alanctl validate
+./scripts/alanctl up
+```
+
+## Umgang mit `.env`
+
+Die lokale `.env` ist betriebsrelevant und bleibt lokal.
+
+Vor jedem Repo-Upgrade:
+
+```bash
+git diff HEAD~1 .env.example
+```
+
+oder allgemeiner:
+
+```bash
+git diff <alter-tag>..<neuer-tag> -- .env.example
+```
+
+Wenn neue Variablen eingefuehrt wurden, muessen diese in die lokale `.env` uebernommen werden.
+
+## Rollback-Regel
+
+Image-Rollback und State-Rollback sind getrennt zu betrachten.
+
+- `rollback-hermes` setzt das letzte bekannte gute Image wieder ein
+- bei problematischer Datenmigration muss zusaetzlich ein Backup-Archiv via `restore` zurueckgespielt werden