71 lines
7.1 KiB
Markdown
71 lines
7.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. |