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

45 lines
6.0 KiB
Markdown

# 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.