# 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///-.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:` und prüft Manager, PHP, Node und Composer. 3. Erfolgreichen Kandidaten mit einem neuen annotierten Tag `v` markieren und den Tag pushen. 4. Tag-Lauf muss erfolgreich sein. Er gibt lokal `pipeline-manager:` 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/` 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 `/.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.