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

7.1 KiB

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.