6. Deployment und Betrieb¶
6.1. Repository- und Release-Struktur¶
Der Root-Checkout enthält die Betriebsdateien; src/ ist der Laravel-Subtree.
Release- und Produktionsoperationen werden aus dem Root ausgeführt. Der
Laravel-Code darf nicht als unabhängiger Produktionscheckout neben dem
Root-Repository aktualisiert werden.
6.2. Vorgesehener Produktionsweg¶
Ein Release und seine Auslieferung laufen über:
./planer release
./planer backup create
./planer update --ref v2026.15.0 --backup-confirmed
release aktualisiert lokal Version, Changelog, Commit und Tag und pusht den
Tag. GitHub Actions baut daraufhin das versionierte Image
pfarrtools/pfarrplaner:vVERSION und veröffentlicht das Handbuch. update
zieht dieses Image, führt Migrationen aus, aktualisiert die öffentlichen Assets
und startet App, Horizon und Scheduler mit Health-Check neu. Der alte Image-
Stand bleibt als Rollback-Grundlage erhalten. Wenn MAIL_POSTFIX_ENABLED=true gesetzt ist,
aktiviert der Updatepfad automatisch das Compose-Profil mail und startet
Postfix gemeinsam mit App, Horizon und Scheduler. Dadurch bleibt der interne
Hostname postfix auch nach einem Containerwechsel erreichbar.
6.3. Docker-Deployment¶
Im Containerbetrieb läuft das Deployment reproduzierbar über das veröffentlichte
Root-Produktionsimage und compose.production.yaml. Entscheidend sind persistente
MariaDB-, Redis- und MinIO-Volumes, konsistente .env-Werte, ein geprüftes
Backup und ein sauberer Umgang mit Migrationen, Horizon und Scheduler.
Die Produktions-Compose-Datei trennt interne Backend- und Mail-Netzwerke von
einem nicht internen sentry-egress-Netzwerk. App, Horizon und Scheduler sind
an dieses Egress-Netzwerk angebunden, damit der Sentry-Client den in
SENTRY_LARAVEL_DSN konfigurierten Host über HTTPS erreichen kann. Der
Egress-Pfad muss in Firewall und DNS des Servers erlaubt sein; die internen
Netzwerke bleiben ohne direkten externen Zugriff.
6.4. Release-Kontext¶
Das Repository enthält Release-Skripte, die neben Versionsständen auch den Neubau und die Auslieferung des Handbuchs berücksichtigen. Manual-Operationen können unabhängig davon ausgeführt werden:
./planer dev manual all
./planer dev manual deploy --dry-run
./planer dev manual deploy
6.5. GitHub-Actions-Deploy auf Produktionshosts¶
Der Release-Workflow kann nach erfolgreichem Image- und Manual-Build einen
seriellen Produktionsdeploy ausführen. Die Zielhosts werden über die
GitHub-Variable PRODUCTION_HOSTS als JSON-Matrix konfiguriert; reale
Hostnamen und Pfade werden dadurch nicht im Repository versioniert:
{
"include": [
{
"name": "prod-a",
"user": "deploy",
"host": "prod-a.example.org",
"path": "/srv/pfarrplaner"
},
{
"name": "prod-b",
"user": "deploy",
"host": "prod-b.example.org",
"path": "/srv/pfarrplaner"
}
]
}
Der Job verwendet das geschützte Environment production sowie die Secrets
PRODUCTION_DEPLOY_SSH_KEY und PRODUCTION_DEPLOY_KNOWN_HOSTS. Pro Host
werden per SSH ./planer prod backup create und anschließend
./planer prod update --ref <Release-Tag> --backup-confirmed ausgeführt. Der
vorhandene Updatepfad wartet danach auf den Produktions-Health-Check; ein
Fehler stoppt den seriellen Rollout.
6.6. Health und Monitoring¶
Für Monitoring ist mindestens der Health-Endpunkt sinnvoll:
GET /api/health
Zusätzlich sollten Sie Caddy, den App-Health-Endpunkt, Horizon, Scheduler, MariaDB, Redis, MinIO und – bei aktiviertem Mail-Profil – Postfix überwachen.