Files
PipelineManager/docs/PROJEKTE-ANBINDEN.md
2026-10-26 14:56:48 +01:00

6.0 KiB

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.

Hinweis im AGENTS.md des angebundenen Projekts

Damit ein Agent im Anwendungsrepository die gemeinsame Werkzeugkette findet, dort einen Hinweis nach diesem Muster hinterlegen und die konkrete freigegebene Version im Projekt pflegen:

Deployments laufen über Gitea mit PipelineManager: https://gitea.stommer.de/Lars/PipelineManager. Vor Pipeline-Änderungen dessen README, AGENTS.md und docs/PROJEKTE-ANBINDEN.md lesen. Dieses Projekt definiert seine Befehle und Ziele in pipeline.toml. Push auf develop testet und deployt Staging; Produktion nur über den vereinbarten Merge nach main und ein ausdrücklich freigegebenes Ziel. Werkzeuge werden im zentralen Image gepflegt, projektspezifische Abläufe hier. Keine lokalen Builds als Voraussetzung für automatische Deployments und keine Geheimnisse im Repository.

Die FeWo-Anbindung enthält diesen Verweis bereits. Die Wiki-Anbindung muss ihn bei ihrer Einrichtung übernehmen.