Werkzeugversion 0.1.1 mit WebP und Betriebsanweisungen für Projekte und Agenten
PipelineManager Image / image (push) Successful in 6s

This commit is contained in:
Lars Stommer committed 2026-10-26 14:40:12 +01:00
1 parent 0e44a4211d
commit 34b6b010fd
9 files changed
+239 -10

No files matched your search

+71
View File
@@ -0,0 +1,71 @@
# 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.
+38
View File
@@ -0,0 +1,38 @@
# Ein Projekt anbinden
## Zuständigkeiten und Voraussetzungen
Gitea startet das veröffentlichte Werkzeug-Image auf einem Docker-fähigen Runner. Das Projekt beschreibt den Zusammenbau und die Prüfungen seines Pakets. Der Manager übernimmt den allgemeinen Dateideploy nach Strato. Es gibt keinen zusätzlichen Dienst, Port oder API-Aufruf.
Das aktuelle Image enthält PHP 8.4, Composer 2, Node 22/npm, Python 3, Git, SSH, curl und tar. Projekte mit weiteren Werkzeugen oder anderen Hauptversionen sind nicht automatisch unterstützt: zuerst eine passende versionierte Werkzeugumgebung bereitstellen. Vertrag 1 unterstützt Git-Archive ohne Symlinks; Git-Submodule/LFS-Inhalte werden nicht automatisch materialisiert.
## Vorgehen
1. `pipeline.toml` nach dem Beispiel im README anlegen. `manager` auf die bereitgestellte Version setzen, eindeutigen Projektnamen wählen.
2. `prepare`: Abhängigkeiten gemäß Lockdateien installieren, externe Quellen reproduzierbar beziehen, Dateien zusammenstellen. Befehle laufen im temporären Export des Git-Commits.
3. `test`: mindestens einen sinnvollen Testbefehl definieren. Ein Fehler verhindert Paket und Upload. Testdatenbanken vom Server trennen.
4. `finalize`: Entwicklungsabhängigkeiten entfernen und das Laufzeitpaket fertigstellen. FeWo entfernt hier zusätzliche Sprach-/Dokumentationsdateien wegen Stratos Dateilimit.
5. `exclude` und `required`: Paket begrenzen und Laufzeit-Pflichtdateien prüfen. Wörtliche relative Pfade verwenden, keine Wildcards. `.env`, `.env.*` und `.git` werden automatisch ausgeschlossen; sonstige Geheimnisdateien zusätzlich ausschließen und möglichst nie committen.
6. `remote.public` auf das öffentliche Verzeichnis setzen. `remote.shared` ordnet persistente Zielpfade Quellen unter `<target>/shared/` zu. Diese Quellen müssen vorher existieren. Zu verlinkende Ziele aus dem Paket ausschließen.
7. `remote.backup` sichert beispielsweise die Datenbank in den persistenten Speicher. `remote.activate` führt benötigte Migrationen/Cache-Kommandos aus. Hooks sind Argumentlisten; `@php` steht für die PHP-CLI auf Strato. Implizite Shell-Auswertung findet nicht statt; notwendige Shell-Skripte ausdrücklich aufrufen.
8. Staging-Ziel mit relativem Webspace-Pfad, Branch, HTTPS-URL und geeignetem `health_path` einrichten. Standard ist `/up`; statische Anwendungen und andere Frameworks müssen den Pfad passend setzen. Healthcheck erwartet HTTP 200, kein projektspezifisches Antwortschema.
9. Produktion zunächst mit `enabled = false` sperren. Für den vereinbarten Ablauf `require_merge = true` und `source_branch = "develop"` setzen. Code-Rollback ersetzt keine Planung kompatibler Datenbankmigrationen.
10. Gitea-Secrets anlegen: `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`; optional `DEPLOY_PORT`. Geprüften Hostschlüssel verwenden. Der private Schlüssel gehört ausschließlich in das Secret.
11. `examples/gitea-deploy.yml` ins Projekt nach `.gitea/workflows/deploy.yml` übernehmen und Image-Version, Runner sowie Pfade prüfen. `.pipeline/` in `.gitignore` aufnehmen.
12. Konfiguration mit `pipeline-manager check` prüfen, auf `develop` pushen, Gitea-Lauf bis einschließlich Deployment verfolgen. Danach tatsächlichen Server-Commit, Backup und Website prüfen. Erst dann die Anbindung als erprobt dokumentieren.
## Referenz FeWo-Stommer
- Repository: https://gitea.stommer.de/Lars/fewo-stommer, Branch `develop`.
- `pipeline.toml`: Composer mit Testabhängigkeiten, npm/Vite, temporäre Test-Konfiguration, Feature-Tests auf SQLite im Speicher; anschließend Composer ohne Entwicklungsabhängigkeiten und Paketbereinigung.
- PDF-Tests laufen direkt mit `php -d memory_limit=512M vendor/bin/phpunit --testsuite=Feature --no-progress`. Das Standardlimit des PHP-Images (128 MB) war zu klein.
- Persistent: `.env`, `storage`, `public/storage`; Backup-Hook `artisan backup:database`; Aktivierung mit Migrationen und Laravel-/Filament-Caches.
- Staging: `test.fewo-stommer.de/`, https://stommer.info, PHP `/opt/RZphp84/bin/php-cli`.
- Produktion: `prod.fewo-stommer.de/`, gesperrt. Die bestehende WordPress-Installation darf nicht überschrieben werden.
- Exakte Laufnachweise stehen in `docs/BETRIEB.md`.
## Beispiel KarateWiki: geplante Anbindung
Dies ist ein Entwurf, noch kein getestetes Profil. Das Gitea-Projekt kann die festgelegte MediaWiki-Version aus einer externen Quelle mit Prüfsumme bzw. festem Commit beziehen und mit versionierten Erweiterungen sowie nicht geheimen Konfigurationsvorlagen kombinieren. Herkunft und Version aller Bestandteile müssen im Projekt nachvollziehbar bleiben. Die allgemeinen Paket-/Übertragungsschritte ändern sich dadurch nicht.
Vor Umsetzung sind die tatsächliche MediaWiki-Version, Erweiterungen, benötigte PHP-Erweiterungen, Tests und Wartungskommandos zu ermitteln. Uploads und geheime lokale Konfiguration gehören in `shared`. Datenbank-Backup, Wartungsfenster, Schema-Aktualisierung und ein möglicher Wiederherstellungsweg müssen projektspezifisch festgelegt werden. Keine FeWo-Artisan-Befehle übernehmen. Der öffentliche Verzeichnispfad muss zum zusammengestellten Paket passen; Dateien außerhalb dieses Pfads sind über den Manager-Zugang gesperrt.