Files
PipelineManager/docs/BETRIEB.md
T
2026-10-26 14:47:00 +01:00

76 lines
8.1 KiB
Markdown

# Betrieb und Nachweise
Stand: 26.10.2026. Einstieg für Menschen und Coding-Agenten. Nach wesentlichen Änderungen fortschreiben; geplante und tatsächlich geprüfte Schritte unterscheiden.
## Architekturentscheidung
Gitea übernimmt Auslöser, Auftragsausführung, Protokolle und Ergebnis. Das versionierte PipelineManager-Image enthält gemeinsame Werkzeuge und Deployment-Mechanismen. Für jeden Auftrag startet der Runner Container aus diesem vorhandenen Image; die Container starten selbst keine Container. Build und Deployment sind getrennt, damit Anwendungstests keine Strato-Zugänge erhalten. Werkzeuge werden bei Containerstart nicht neu installiert. Projektabhängigkeiten werden gemäß Lockdateien bereitgestellt und Downloads gecacht.
Kein dauerhaft laufender Manager, keine eigene HTTP-API, keine zusätzlichen Ports und kein MCP. Diese Entscheidung wurde nach Vergleich mit einem zentralen Dienst bewusst gewählt. Ein Dienst wäre erst bei Bedarf an eigener projektübergreifender Auftragsverwaltung neu zu bewerten.
## Tatsächliche Infrastruktur
| Bestandteil | Stand |
|---|---|
| Repository | https://gitea.stommer.de/Lars/PipelineManager |
| Lokales Verzeichnis | `C:\dev\pipelinemanager` |
| Ausführender Runner | `Raspi5-Paperless`, ID 2, bisheriges Host-Label `ubuntu-latest`, act_runner 0.2.11 |
| Zweiter Runner | `llm-node-runner`, Label `linux_host`; bisher kein freigegebenes Manager-Image dort |
| Pi-Verzeichnis | `/home/lars/docker/pipeline-manager/` |
| Download-Caches | `cache/composer/`, `cache/npm/` |
| Sicherungen | `backups/<project>/<environment>/<UTC-Zeit>-<commit>.tar.gz` |
| Netzwerk | Kein vom Manager veröffentlichter Hostport; ausgehend Quellen/Downloads und SSH/HTTPS zu Strato |
| Erstes Image | `pipeline-manager:0.1.0`, Tag `v0.1.0`, Commit `0e44a42`; Freigabelauf 4649 erfolgreich |
| Nächste Werkzeugversion | `0.1.1`: ergänzt im FeWo-Pilot fehlende GD-WebP-Unterstützung; Freigabenachweis wird ergänzt |
Die Manager-Verzeichnisse wurden tatsächlich auf dem Pi angelegt und mit restriktiven Rechten geprüft. Bestehende Portbelegung wurde im Image-Lauf 4648 gelesen; andere Anwendungen wurden nicht geändert. Das Image liegt lokal auf diesem Runner. Vor Ausweitung auf andere Rechner Architektur und Imagebereitstellung klären. Das Label ist kein dauerhafter Identitätsnachweis: bei zusätzlichen Runnern mit demselben Label muss die Zuordnung eindeutiger werden.
## Release-Verfahren
1. Änderungen prüfen, Manager-Tests ausführen. `VERSION` und Python-Versionskennung müssen zusammenpassen.
2. Auf `main` oder `develop` pushen. Gitea baut `pipeline-manager:<commit>` und prüft Manager, PHP, Node und Composer.
3. Erfolgreichen Kandidaten mit einem neuen annotierten Tag `v<VERSION>` markieren und den Tag pushen.
4. Tag-Lauf muss erfolgreich sein. Er gibt lokal `pipeline-manager:<VERSION>` frei. Bereits belegte Versionen werden nicht ersetzt.
5. In Anwendungen sowohl `pipeline.toml` als auch Workflow auf diese Version setzen. Pilotlauf verfolgen.
Image-Build ist vom Anwendungsdeploy getrennt. Neue Projekte erfordern keinen Image-Neubau, solange die vorhandenen Werkzeuge ausreichen. Dokumentationsänderungen bauen einen Kandidaten, verändern aber nicht das bereits freigegebene Image.
## FeWo-Pilot
- Staging: `test.fewo-stommer.de/` auf Strato, https://stommer.info.
- Produktion: `prod.fewo-stommer.de/` angelegt, ohne eingerichtete Laufzeit-Konfiguration/Datenbank, in FeWo ausdrücklich gesperrt. Bestehendes WordPress bleibt bestehen.
- Eigener Pipeline-SSH-Schlüssel eingerichtet und die Anmeldung separat geprüft. Privater Teil liegt als Gitea-Repository-Secret `DEPLOY_SSH_KEY`; zusätzlich `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_KNOWN_HOSTS`. Kein privater Schlüssel in Git oder Image.
- Lauf 4650, Commit `01900d6`: Tests wegen PHP-Standardlimit 128 MB abgebrochen, vor Upload. FeWo-Testkommando daraufhin auf 512 MB angepasst.
- Lauf 4651, Commit `92fb01d`: alle 285 Tests ausgeführt, acht Fehler ausschließlich wegen fehlendem `imagewebp()` im Image. Kein Upload. Korrektur erfolgt durch neue Image-Version statt Änderung der veröffentlichten Version 0.1.0.
Lauf-URLs: `https://gitea.stommer.de/Lars/fewo-stommer/actions/runs/<ID>` bzw. im Manager-Repository für Image-Läufe.
## Fehlerbehandlung und Grenzen
- **Kein Image:** passenden Runner und erfolgreichen Versions-Freigabelauf prüfen. Nicht stillschweigend auf `latest` wechseln.
- **Testfehler:** Gitea-Buildlog lesen; Anwendung/Testumgebung korrigieren. Keine Tests überspringen, um einen Deploy zu erzwingen.
- **Exitcode 3 bei check:** Ziel bewusst gesperrt; Workflow überspringt Build/Deployment. Das ist keine Produktionsfreigabe.
- **Paket existiert:** `prepare` überschreibt kein vorhandenes Artefakt. Normaler neuer Checkout entfernt das ignorierte `.pipeline/`-Verzeichnis; vor manuellem Wiederanlauf nur dessen konkretes altes Artefakt entfernen.
- **Veralteter Auftrag:** Remote-Branch stimmt nicht mehr mit dem geprüften Commit überein; der Manager verhindert den Deploy. Aktuellen Lauf verwenden.
- **SSH-Fehler:** Secrets/Autorisierung und verifizierten Hostschlüssel prüfen; keine privaten Inhalte ausgeben, keine Hostprüfung abschalten.
- **Backupfehler:** kein Upload; geschütztes Backup-Verzeichnis und projektspezifischen Datenbank-Hook prüfen. Fehlgeschlagene Archive nicht als verifizierte Sicherung behandeln.
- **Sperre besteht:** aktiven Auftrag prüfen. Nach Absturz nur nach geklärtem Zustand gezielt `<target>/.deploy-lock` entfernen; niemals fremde Jobs entsperren.
- **Aktivierung schlägt vor Umschaltung fehl:** bisheriger Code bleibt aktiv; Migrationen könnten bereits Änderungen vorgenommen haben. Logs und Datenbank prüfen.
- **HTTP-Healthcheck schlägt fehl:** Rückfall auf vorherige Codeversion wird versucht; schlägt SSH/Rückfall selbst fehl, ist manuelle Prüfung nötig. Bei Erstinstallation wird Zugriff gesperrt. Datenbankmigrationen werden nicht rückgängig gemacht.
- **Erfolgreicher Deploy:** alte Releases werden wegen Stratos Dateilimit entfernt. Ein späterer Rücksprung benötigt einen erneuten Build eines alten Quellstands unter Beachtung der Branch-Prüfung; es gibt bisher keinen allgemeinen Manager-Redeploy-/Rollback-CLI-Befehl.
Backups enthalten `.env`, persistente Dateien und den durch den Backup-Hook erzeugten Datenbank-Dump. Sie liegen geschützt auf dem Pi. Offsite-Kopie, Aufbewahrungsregeln und ein praktisch geprüfter Restore sind separate Betriebsaufgaben und werden nicht automatisch durch den Manager erledigt. Deployments erhalten derzeit keinen automatisch erzeugten Git-Deploy-Tag; Workflow-Commit, Paketmetadaten und Server-`REVISION` bilden den Nachweis.
## Prüfen ohne API-Dienst
- Manager-Logik: `python -m unittest discover -s tests -v`.
- Image: Gitea-Image-Build mit integriertem Testlauf und Werkzeugaufrufen; WebP-Fähigkeit wird beim Image-Build geprüft.
- Ausführung: Runner-Status, Job-Schritte, Rückgabecode und Gitea-Logs.
- Strato: HTTPS-Healthcheck nach Aktivierung; zusätzlich aktive Release-Verknüpfung und `REVISION` kontrollieren.
Ein Container-Lebenszeichen wäre kein Beleg für ein funktionierendes Deployment. Maßgeblich ist der vollständige Auftrag bis zur erreichbaren Anwendung.
## Weitere Pilotbefunde
- Image-Kandidat 0.1.1, Commit `34b6b01`: Lauf 4652 grün; Versionsfreigabe `v0.1.1`: Lauf 4653 grün.
- FeWo-Lauf 4654: 285 Tests grün und Paket mit 10.552 Vendor-Dateien erstellt. Deployment stoppte vor SSH-Verbindung mit `No user exists for uid 1000`. Das Image enthält keinen festen Pi-Benutzer. Der Deployment-Aufruf bindet deshalb die Benutzerliste `/etc/passwd` des Linux-Runners schreibgeschützt ein, damit OpenSSH die mit `--user` gewählte UID auflösen kann. Die Passwort-Hashes aus `/etc/shadow` werden nicht eingebunden. Die Workflow-Vorlage enthält diese Zuordnung.
- Docker meldet auf dem Pi fehlende Memory-Cgroup-Unterstützung: `--memory` wird dort verworfen. Diese Option ist derzeit keine durchgesetzte Speichergrenze. PHP-Tests sind separat auf 512 MB begrenzt; für verbindliche Container-Speichergrenzen ist eine gesonderte Pi-Betriebskonfiguration nötig. Keine Kernel-/Hostkonfiguration wurde während des Piloten verändert.