7.8 KiB
PipelineManager
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
- Neue Projekte anbinden
- Anweisungen für Coding-Agenten
- Gitea-Workflow-Vorlage
Aufteilung
- Dieses Repository enthält das Werkzeug-Image, die Konfigurationsschnittstelle und die gemeinsame Deployment-Logik.
- Jede Anwendung enthält eine
pipeline.toml: eigene Vorbereitungs- und Testbefehle, benötigte Dateien, persistente Pfade und Zielverzeichnisse. Fachlogik und Mandantendaten bleiben in der Anwendung. - Gitea startet die Aufträge. Ein zusätzlicher HTTP-Dienst ist für Version 0.1 nicht erforderlich.
Ablauf eines Anwendungsdeployments
flowchart TD
Push[Push develop / Merge nach main] --> Gitea[Gitea-Workflow auf dem Runner]
Image[Vorhandenes freigegebenes Werkzeug-Image] --> Build
Image --> Deploy
Gitea --> Build[Container: Commit vorbereiten und testen]
Build --> Paket[Geprüftes Paket und SHA256]
Paket --> Deploy[Container: sichern und deployen]
Secrets[Gitea Secrets] --> Deploy
Deploy --> Strato[Strato: shared erhalten, neue Version aktivieren]
Strato --> Health[HTTPS-Healthcheck]
Health --> Ergebnis[Ergebnis und Logs in Gitea]
Die Container sind aufeinanderfolgende Prozesse auf dem Pi. Es gibt keinen Container, der einen weiteren Container erzeugt. Das Werkzeug-Image bleibt erhalten; Paketvorbereitung und Deployment verwenden dieselbe festgelegte Version. Abhängigkeiten des Projekts werden nach seinen Lockdateien installiert, gemeinsame Downloads bleiben im Cache.
Image-Lebenszyklus
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.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.
Befehle
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.
pipeline-manager check --project /workspace
pipeline-manager check --project /workspace --environment staging
pipeline-manager prepare --project /workspace --artifact /workspace/.pipeline/release.tgz
pipeline-manager deploy --project /workspace --environment staging \
--artifact /workspace/.pipeline/release.tgz --backup-root /backups
check --environment liefert Exitcode 3 für ein bewusst gesperrtes Ziel, sonst 0 bei gültiger Konfiguration oder 1 bei einem Fehler. prepare exportiert exakt den aktuellen Git-Commit in ein temporäres Verzeichnis, führt prepare → test → finalize aus und erstellt Paket, Prüfsumme und Commit-/Projekt-/Testnachweis. Uncommittete Änderungen werden nicht übernommen. Ein Testfehler verhindert das Paket.
deploy prüft Ziel, Branch, Workflow-Commit, aktuellen Remote-Branch und Paket. Dann folgen Deployment-Sperre, Backup von Datenbank und persistenten Dateien, Upload mit serverseitiger Prüfsumme, Aktivierung, Gesundheitscheck und Aufräumen. Eine fehlgeschlagene Sicherung verhindert den Upload. Ein fehlgeschlagener Gesundheitscheck löst den Rückfall auf die vorige Codeversion aus. Datenbank-Migrationen werden dabei nicht zurückgenommen.
Projektkonfiguration, Vertrag 1
schema = 1
project = "example"
manager = "0.1.1"
[build]
prepare = [["npm", "ci"], ["npm", "run", "build"]]
test = [["npm", "test"]]
finalize = []
exclude = ["node_modules", ".gitea", "tests", "docs"]
required = ["dist/index.html"]
[remote]
public = "dist"
backup = []
activate = []
[targets.staging]
branch = "develop"
path = "test.example.de"
url = "https://test.example.de"
health_path = "/"
enabled = true
[targets.production]
branch = "main"
path = "prod.example.de"
url = "https://example.de"
health_path = "/"
enabled = false
Hooks sind Argumentlisten ohne implizite Shell-Auswertung. Für PHP auf Strato ersetzt @php die PHP-CLI der Zielkonfiguration (Standard /opt/RZphp84/bin/php-cli). Beispiel: activate = [["@php", "artisan", "migrate", "--force", "--no-interaction"]]. Ein Projekt kann in [build.environment] seine isolierten Test-Einstellungen setzen. Die Anwendung FeWo liefert das Laravel-Pilotprofil.
Persistente Pfade werden über [remote.shared] zugeordnet, beispielsweise ".env" = ".env", storage = "storage", "public/storage" = "storage/app/public". Diese Quellen müssen unter <target>/shared/ vor der Erstinstallation existieren. Sie werden nicht durch Code-Deployments erzeugt oder mit Daten einer anderen Umgebung befüllt. Die Projekt-Ausschlussliste muss die persistenten Ziele aus dem Paket ausschließen.
Runner, Verzeichnisse und Geheimnisse
Die Anwendung startet das Image auf dem bisherigen Docker-fähigen Host-Runner. Standard-Verzeichnisse auf dem Pi folgen Tsumugu:
/home/lars/docker/pipeline-manager/
cache/composer/
cache/npm/
backups/<project>/<environment>/
Diese Verzeichnisse werden gezielt in den Job-Container gemountet. Der Container erhält weder den Docker-Socket noch andere Anwendungsverzeichnisse. Er läuft mit UID/GID des Runners und mit Ressourcenlimits. Build und Deployment sind getrennte Containeraufrufe: Der Build bekommt keine Strato-Zugänge.
Nur der Deployment-Schritt erhält die Secrets der jeweiligen Anwendung: DEPLOY_HOST, DEPLOY_USER, optional DEPLOY_PORT, DEPLOY_SSH_KEY (Schlüsselinhalt) und DEPLOY_KNOWN_HOSTS (bereits geprüfte SSH-Hostschlüssel). Private Schlüssel werden kurzfristig mit Modus 0600 geschrieben und anschließend entfernt. Nichts davon gehört ins Image oder Repository. Backups enthalten sensible Daten einschließlich Server-Konfiguration und liegen mit restriktiven Rechten außerhalb des kurzlebigen Containers.
Prüfung und aktueller Stand
python -m unittest discover -s tests -v
docker build -t pipeline-manager:test .
docker run --rm pipeline-manager:test pipeline-manager --version
Die lokalen Manager-Tests decken eine statische Anwendung, Commit-Auswahl, Testfehler, Paketmanipulation, Pfadwechsel, Geheimnisdateien, gesperrte Ziele, Branch-/Commit-Verwechslungen, veraltete Jobs, Sicherungsreihenfolge, Sperren und Rückfall ab. Der Docker-Build und echte Runner-/Strato-Nachweise werden getrennt protokolliert. Eine erfolgreiche lokale Python-Suite allein ist keine Freigabe für Produktion.
Tsumugu wurde ausschließlich als Referenz gelesen und bleibt unverändert. Seine parallelen Deploy-/Testläufe und --no-cache-Builds sind nicht Teil dieses Managers: Die Tests laufen vor dem Upload am exakten Commit in einem eigenen Arbeitsverzeichnis.