Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
34b6b010fd |
No files matched your search
@@ -0,0 +1,50 @@
|
|||||||
|
# PipelineManager: Anweisungen für Coding-Agenten
|
||||||
|
|
||||||
|
## Zuerst lesen
|
||||||
|
|
||||||
|
1. `README.md`: Architektur, Befehle und Konfigurationsvertrag.
|
||||||
|
2. `docs/BETRIEB.md`: tatsächlicher Betriebsstand, Nachweise und Fehlerbehandlung.
|
||||||
|
3. `docs/PROJEKTE-ANBINDEN.md`: neue Anwendungen und Referenz-Workflow.
|
||||||
|
4. Vor Änderungen `git status` prüfen; fremde Änderungen erhalten.
|
||||||
|
|
||||||
|
## Vereinbarte Architektur
|
||||||
|
|
||||||
|
PipelineManager ist eine wiederverwendbare Deployment-Werkzeugkette, kein dauerhaft laufender API-Dienst. Gitea verwaltet Aufträge und Logs. Der Runner startet kurzlebige Container aus einem bereits gebauten, versionierten Image. Container erzeugen selbst keine weiteren Container. Kein Docker-Socket im Job-Container, keine veröffentlichten Ports, kein MCP erforderlich. Diese Architektur nicht ohne ausdrückliche Abstimmung durch einen Server/API-Dienst ersetzen.
|
||||||
|
|
||||||
|
- Dieses Repository: Werkzeuge, Konfigurationsvertrag, generische Paketprüfung, Sicherung, SSH-Übertragung, Aktivierung und Rückfall.
|
||||||
|
- Anwendungsrepository: `pipeline.toml`, eigene Tests, Build-/Aktivierungsbefehle und Gitea-Workflow.
|
||||||
|
- Strato: PHP-/Datei-Laufzeit, persistente Daten und Server-Konfiguration. Keine Node-Installation zur Laufzeit.
|
||||||
|
- Keine Laravel-, MediaWiki-, Mandanten- oder projektspezifische Fachlogik im Manager.
|
||||||
|
|
||||||
|
## Änderungen am Manager
|
||||||
|
|
||||||
|
- Python-Standardbibliothek, Python >= 3.11; bestehende Konventionen verwenden.
|
||||||
|
- Vor Codeänderungen vorhandene Tests lesen. `python -m unittest discover -s tests -v` ausführen; für Verhaltensänderungen gezielte Regressionstests ergänzen.
|
||||||
|
- Remote-Shell zusätzlich mit `bash -n manager/remote.sh` prüfen; der echte Image-Build läuft über Gitea auf dem Pi.
|
||||||
|
- Release-Version in `VERSION` und `manager/cli.py` zusammen ändern. Bestehende `v*`-Tags oder freigegebene Images niemals auf einen anderen Stand umbiegen.
|
||||||
|
- Kandidaten-Build grün abwarten, danach neuen Versionstag veröffentlichen und dessen Freigabelauf prüfen. Anwendungs-Konfiguration und Workflow müssen dieselbe Manager-Version verwenden.
|
||||||
|
- Dokumentationsänderungen benötigen keine neue Werkzeugversion. Ein neuer Kandidaten-Build gibt noch keine neue stabile Version frei.
|
||||||
|
- Anwendungen und produktive Dienste auf dem Pi nicht verändern, um Manager-Tests zum Bestehen zu bringen.
|
||||||
|
|
||||||
|
## Änderungen in einer Anwendung
|
||||||
|
|
||||||
|
- Quellstände einschließlich externer Quellen und Erweiterungen fest pinnen; keine beweglichen `latest`-/Branch-Downloads als Releasebasis.
|
||||||
|
- Tests im Container vor dem Upload ausführen. Kein voller Build auf dem Entwicklungsrechner als Voraussetzung für den CI-Weg.
|
||||||
|
- Build-Container bekommt keine Strato-Secrets. Deployment-Container bekommt sie nur im Deployment-Schritt.
|
||||||
|
- Pflichtdateien und Ausschlüsse ausdrücklich konfigurieren. Symlinks im Quell-Export oder Paket sind in Vertrag 1 nicht unterstützt. Exclude-Pfade sind wörtliche relative Pfade, keine Globs.
|
||||||
|
- Schreibbare Dateien, Uploads und Konfiguration über `remote.shared` erhalten. `shared` vor Erstinstallation separat einrichten; niemals Daten anderer Ziele übernehmen.
|
||||||
|
- Keine Änderungen nach `prepare` am erzeugten Paket; Paket und SHA256 gehören zusammen.
|
||||||
|
- `develop` -> Test; Merge-Commit von `develop` nach `main` -> Produktion. Gesperrte Ziele nicht eigenmächtig aktivieren.
|
||||||
|
|
||||||
|
## Geheimnisse und Grenzen
|
||||||
|
|
||||||
|
- Private Schlüssel, Passwörter und Tokens ausschließlich in Gitea Secrets oder geschützter Server-Konfiguration. Niemals in Git, Beispiele, Image, Logs oder Chat schreiben.
|
||||||
|
- Hostschlüssel vorab verifizieren; StrictHostKeyChecking nicht abschalten.
|
||||||
|
- Backups enthalten `.env` und Datenbankdaten. Nur geschützte persistente Verzeichnisse verwenden; niemals als öffentliche CI-Artefakte veröffentlichen.
|
||||||
|
- Pi-Dateien unter `/home/lars/docker/pipeline-manager/`; keine offenen Ports erforderlich. Andere Docker-Projekte nicht anfassen.
|
||||||
|
- Ein freigegebenes Image liegt aktuell nur lokal auf Raspi5-Paperless. Nicht auf einen anderen Runner wechseln, ohne dort ein passendes Image bereitzustellen.
|
||||||
|
- Keine parallelen Aufträge gegen dasselbe Ziel erzwingen, keine fremden Sperren entfernen. Rückfall betrifft Code; Datenbankänderungen werden nicht automatisch rückgängig gemacht.
|
||||||
|
|
||||||
|
## Abschluss und Übergabe
|
||||||
|
|
||||||
|
Nach wesentlichen Änderungen Betriebsstand und Nachweise aktualisieren: Commit, Image-Version, Gitea-Lauf, Ziel, Tests, HTTP-Prüfung, offene Punkte. Ein grüner Unit-Testlauf allein ist kein erfolgreicher Strato-Deploy. Tatsächlich ausgeführte Prüfungen von geplanten Prüfungen unterscheiden.
|
||||||
+3
-2
@@ -4,9 +4,10 @@ FROM php:8.4-cli-bookworm
|
|||||||
|
|
||||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||||
python3 git openssh-client curl ca-certificates tar gzip unzip \
|
python3 git openssh-client curl ca-certificates tar gzip unzip \
|
||||||
libicu-dev libzip-dev libonig-dev libsqlite3-dev libpng-dev libjpeg62-turbo-dev libfreetype6-dev \
|
libicu-dev libzip-dev libonig-dev libsqlite3-dev libpng-dev libjpeg62-turbo-dev libfreetype6-dev libwebp-dev \
|
||||||
&& docker-php-ext-configure gd --with-freetype --with-jpeg \
|
&& docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
|
||||||
&& docker-php-ext-install -j2 bcmath exif gd intl mbstring pdo_mysql pdo_sqlite zip \
|
&& docker-php-ext-install -j2 bcmath exif gd intl mbstring pdo_mysql pdo_sqlite zip \
|
||||||
|
&& php -r 'if (!function_exists("imagewebp")) { exit(1); }' \
|
||||||
&& rm -rf /var/lib/apt/lists/*
|
&& rm -rf /var/lib/apt/lists/*
|
||||||
COPY --from=node /usr/local/bin/node /usr/local/bin/node
|
COPY --from=node /usr/local/bin/node /usr/local/bin/node
|
||||||
COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
|
COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
|
||||||
|
|||||||
@@ -2,6 +2,13 @@
|
|||||||
|
|
||||||
Gemeinsame, versionierte Werkzeuge für Tests, Dateivorbereitung und atomare Deployments nach Strato. Die Anwendung wird weiter bei Strato betrieben. Der Manager läuft nur während eines Auftrags als Docker-Container auf einem Gitea-Runner.
|
Gemeinsame, versionierte Werkzeuge für Tests, Dateivorbereitung und atomare Deployments nach Strato. Die Anwendung wird weiter bei Strato betrieben. Der Manager läuft nur während eines Auftrags als Docker-Container auf einem Gitea-Runner.
|
||||||
|
|
||||||
|
## Einstieg
|
||||||
|
|
||||||
|
- [Betrieb, Release-Verfahren und Pilotnachweise](docs/BETRIEB.md)
|
||||||
|
- [Neue Projekte anbinden](docs/PROJEKTE-ANBINDEN.md)
|
||||||
|
- [Anweisungen für Coding-Agenten](AGENTS.md)
|
||||||
|
- [Gitea-Workflow-Vorlage](examples/gitea-deploy.yml)
|
||||||
|
|
||||||
## Aufteilung
|
## Aufteilung
|
||||||
|
|
||||||
- Dieses Repository enthält das Werkzeug-Image, die Konfigurationsschnittstelle und die gemeinsame Deployment-Logik.
|
- Dieses Repository enthält das Werkzeug-Image, die Konfigurationsschnittstelle und die gemeinsame Deployment-Logik.
|
||||||
@@ -12,13 +19,13 @@ Gemeinsame, versionierte Werkzeuge für Tests, Dateivorbereitung und atomare Dep
|
|||||||
|
|
||||||
Ein Push auf `main` oder `develop` baut auf `Raspi5-Paperless` (bestehendes Label `ubuntu-latest`) ein Kandidaten-Image `pipeline-manager:<commit>`. Der Docker-Build installiert die Werkzeuge im Image und führt die Manager-Tests aus. Auf dem Host werden keine Pakete installiert. Der Ansatz folgt Tsumugus vorhandenen Docker-Aufträgen, verwendet aber Docker-Caches statt `--no-cache`.
|
Ein Push auf `main` oder `develop` baut auf `Raspi5-Paperless` (bestehendes Label `ubuntu-latest`) ein Kandidaten-Image `pipeline-manager:<commit>`. Der Docker-Build installiert die Werkzeuge im Image und führt die Manager-Tests aus. Auf dem Host werden keine Pakete installiert. Der Ansatz folgt Tsumugus vorhandenen Docker-Aufträgen, verwendet aber Docker-Caches statt `--no-cache`.
|
||||||
|
|
||||||
Nach grünem Image-Build wird derselbe Stand mit `v0.1.0` markiert. Der Tag-Workflow prüft und gibt lokal `pipeline-manager:0.1.0` frei. Eine bereits belegte Versionskennung wird nicht auf ein anderes Image umgebogen. Anwendungen verwenden eine konkrete freigegebene Version. Nur wenn Manager oder Werkzeuge geändert werden, entsteht eine neue Version. Ein Container wird je Auftrag neu gestartet; das Image und die gemounteten Download-Caches bleiben erhalten.
|
Nach grünem Image-Build wird derselbe Stand mit `v0.1.1` markiert. Der Tag-Workflow prüft und gibt lokal `pipeline-manager:0.1.1` frei. Eine bereits belegte Versionskennung wird nicht auf ein anderes Image umgebogen. Anwendungen verwenden eine konkrete freigegebene Version. Nur wenn Manager oder Werkzeuge geändert werden, entsteht eine neue Version. Ein Container wird je Auftrag neu gestartet; das Image und die gemounteten Download-Caches bleiben erhalten.
|
||||||
|
|
||||||
Die erste Lieferung baut nativ auf dem ausgewählten Pi. Das Image ist dort lokal vorhanden; ein anderer Runner darf es erst verwenden, wenn es auf seiner passenden CPU-Architektur ebenfalls bereitgestellt wurde. Gemeinsame Registry und Multiarch-Veröffentlichung sind eine spätere Erweiterung, kein verstecktes Erfordernis für den ersten Pi.
|
Die erste Lieferung baut nativ auf dem ausgewählten Pi. Das Image ist dort lokal vorhanden; ein anderer Runner darf es erst verwenden, wenn es auf seiner passenden CPU-Architektur ebenfalls bereitgestellt wurde. Gemeinsame Registry und Multiarch-Veröffentlichung sind eine spätere Erweiterung, kein verstecktes Erfordernis für den ersten Pi.
|
||||||
|
|
||||||
## Befehle
|
## Befehle
|
||||||
|
|
||||||
Im Image stehen PHP 8.4 mit den benötigten Erweiterungen, Composer 2, Node 22/npm, Python 3, Git, SSH, curl und tar zur Verfügung. Die Manager-Logik verwendet nur die Python-Standardbibliothek.
|
Im Image stehen PHP 8.4 mit GD einschließlich WebP und den weiteren benötigten Erweiterungen, Composer 2, Node 22/npm, Python 3, Git, SSH, curl und tar zur Verfügung. Die Manager-Logik verwendet nur die Python-Standardbibliothek.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
pipeline-manager check --project /workspace
|
pipeline-manager check --project /workspace
|
||||||
@@ -37,7 +44,7 @@ pipeline-manager deploy --project /workspace --environment staging \
|
|||||||
```toml
|
```toml
|
||||||
schema = 1
|
schema = 1
|
||||||
project = "example"
|
project = "example"
|
||||||
manager = "0.1.0"
|
manager = "0.1.1"
|
||||||
|
|
||||||
[build]
|
[build]
|
||||||
prepare = [["npm", "ci"], ["npm", "run", "build"]]
|
prepare = [["npm", "ci"], ["npm", "run", "build"]]
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
name: Deploy mit PipelineManager
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [develop, main]
|
||||||
|
workflow_dispatch:
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
deploy:
|
||||||
|
# Raspi5-Paperless: existing host runner; all PHP/Node work happens inside the image.
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
env:
|
||||||
|
PIPELINE_IMAGE: pipeline-manager:0.1.1
|
||||||
|
PIPELINE_HOME: /home/lars/docker/pipeline-manager
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
fetch-depth: 0
|
||||||
|
|
||||||
|
- name: Anwendung im Manager-Container vorbereiten und testen
|
||||||
|
id: build
|
||||||
|
run: |
|
||||||
|
set -eu
|
||||||
|
case "$GITHUB_REF" in
|
||||||
|
refs/heads/develop) TARGET=staging ;;
|
||||||
|
refs/heads/main) TARGET=production ;;
|
||||||
|
*) echo 'Unzulässiger Branch'; exit 1 ;;
|
||||||
|
esac
|
||||||
|
docker image inspect "$PIPELINE_IMAGE" >/dev/null
|
||||||
|
STATUS=0
|
||||||
|
docker run --rm --user "$(id -u):$(id -g)" \
|
||||||
|
-v "$(pwd -P):/workspace:ro" "$PIPELINE_IMAGE" \
|
||||||
|
pipeline-manager check --environment "$TARGET" || STATUS=$?
|
||||||
|
if [ "$STATUS" = 3 ]; then
|
||||||
|
echo 'enabled=false' >> "$GITHUB_OUTPUT"
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
test "$STATUS" = 0
|
||||||
|
umask 077
|
||||||
|
mkdir -p "$PIPELINE_HOME/cache/composer" "$PIPELINE_HOME/cache/npm" "$PIPELINE_HOME/backups" .pipeline
|
||||||
|
docker run --rm --user "$(id -u):$(id -g)" --cpus=2 --memory=2g --pids-limit=512 \
|
||||||
|
-e HOME=/tmp \
|
||||||
|
-v "$(pwd -P):/workspace" \
|
||||||
|
-v "$PIPELINE_HOME/cache:/cache" "$PIPELINE_IMAGE" \
|
||||||
|
pipeline-manager prepare
|
||||||
|
echo "target=$TARGET" >> "$GITHUB_OUTPUT"
|
||||||
|
echo 'enabled=true' >> "$GITHUB_OUTPUT"
|
||||||
|
|
||||||
|
- name: Sichern und nach Strato übertragen
|
||||||
|
if: steps.build.outputs.enabled == 'true'
|
||||||
|
env:
|
||||||
|
TARGET: ${{ steps.build.outputs.target }}
|
||||||
|
DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
|
||||||
|
DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
|
||||||
|
DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
|
||||||
|
run: |
|
||||||
|
set -eu
|
||||||
|
docker run --rm --user "$(id -u):$(id -g)" --cpus=1 --memory=512m --pids-limit=128 \
|
||||||
|
-e GITHUB_REF -e GITHUB_SHA -e DEPLOY_HOST -e DEPLOY_USER -e DEPLOY_SSH_KEY -e DEPLOY_KNOWN_HOSTS \
|
||||||
|
-v "$(pwd -P):/workspace:ro" \
|
||||||
|
-v "$PIPELINE_HOME/backups:/backups" "$PIPELINE_IMAGE" \
|
||||||
|
pipeline-manager deploy --environment "$TARGET" --backup-root /backups
|
||||||
+1
-1
@@ -13,7 +13,7 @@ import time
|
|||||||
import tomllib
|
import tomllib
|
||||||
import urllib.request
|
import urllib.request
|
||||||
|
|
||||||
VERSION = "0.1.0"
|
VERSION = "0.1.1"
|
||||||
NAME = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$")
|
NAME = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$")
|
||||||
COMMIT = re.compile(r"^[0-9a-f]{40}$")
|
COMMIT = re.compile(r"^[0-9a-f]{40}$")
|
||||||
|
|
||||||
|
|||||||
@@ -11,7 +11,7 @@ import tempfile
|
|||||||
import unittest
|
import unittest
|
||||||
from unittest.mock import patch
|
from unittest.mock import patch
|
||||||
|
|
||||||
from manager.cli import PipelineError, deploy, digest, inspect_package, load_config, prepare, render_remote
|
from manager.cli import VERSION, PipelineError, deploy, digest, inspect_package, load_config, prepare, render_remote
|
||||||
|
|
||||||
|
|
||||||
class ManagerTests(unittest.TestCase):
|
class ManagerTests(unittest.TestCase):
|
||||||
@@ -20,7 +20,7 @@ class ManagerTests(unittest.TestCase):
|
|||||||
self.addCleanup(self.temp.cleanup)
|
self.addCleanup(self.temp.cleanup)
|
||||||
self.root = Path(self.temp.name)
|
self.root = Path(self.temp.name)
|
||||||
self.config = {
|
self.config = {
|
||||||
"schema": 1, "project": "static-demo", "manager": "0.1.0",
|
"schema": 1, "project": "static-demo", "manager": VERSION,
|
||||||
"build": {"prepare": [], "test": [[sys.executable, "-c", "pass"]], "finalize": [],
|
"build": {"prepare": [], "test": [[sys.executable, "-c", "pass"]], "finalize": [],
|
||||||
"exclude": ["node_modules"], "required": ["web/index.html"]},
|
"exclude": ["node_modules"], "required": ["web/index.html"]},
|
||||||
"remote": {"public": "web", "shared": {}, "backup": [], "activate": []},
|
"remote": {"public": "web", "shared": {}, "backup": [], "activate": []},
|
||||||
@@ -208,7 +208,7 @@ class ManagerTests(unittest.TestCase):
|
|||||||
def test_configuration_rejects_unsafe_targets_and_incompatible_versions(self):
|
def test_configuration_rejects_unsafe_targets_and_incompatible_versions(self):
|
||||||
path = self.root / "pipeline.toml"
|
path = self.root / "pipeline.toml"
|
||||||
for directory in ("../outside", "/absolute", "x;command", "a//b"):
|
for directory in ("../outside", "/absolute", "x;command", "a//b"):
|
||||||
path.write_text(f'schema=1\nproject="demo"\nmanager="0.1.0"\n[build]\ntest=[["true"]]\n[targets.staging]\npath="{directory}"\nurl="https://example.test"\nenabled=true\n')
|
path.write_text(f'schema=1\nproject="demo"\nmanager="{VERSION}"\n[build]\ntest=[["true"]]\n[targets.staging]\npath="{directory}"\nurl="https://example.test"\nenabled=true\n')
|
||||||
with self.subTest(directory=directory), self.assertRaises(PipelineError):
|
with self.subTest(directory=directory), self.assertRaises(PipelineError):
|
||||||
load_config(path)
|
load_config(path)
|
||||||
path.write_text('schema=1\nproject="demo"\nmanager="9.0.0"\n')
|
path.write_text('schema=1\nproject="demo"\nmanager="9.0.0"\n')
|
||||||
|
|||||||
Reference in new issue
Block a user