2. Installation und Erstbetrieb¶
Dieses Kapitel beschreibt die vollständige Einrichtung einer Pfarrplaner-Instanz aus dem Root-Repository. Es richtet sich an technische Betreiberinnen und Betreiber. Der produktive Weg verwendet compose.production.yaml; compose.yaml ist für die lokale Entwicklung und die Manual-/Testwerkzeuge bestimmt.
2.1. 1. Voraussetzungen¶
Benötigt werden:
- ein Linux-Server oder eine lokale Linux-/Docker-Umgebung,
- Docker Engine mit Docker Compose v2,
- Git für den Checkout,
- eine öffentliche DNS-Adresse und ein vorgeschalteter HTTPS-fähiger Webserver für Produktion,
- ausreichend Speicherplatz für MariaDB, Redis, MinIO-Objekte, Backups und Container-Images.
Der Server muss die verwendeten Container-Images aus den konfigurierten Registries beziehen können. Für produktive Images werden die freigegebenen Tags verwendet; Infrastruktur-Images sollten in der Betriebsdokumentation mit dem geprüften Stand festgehalten werden.
2.2. 2. Repository und Konfiguration¶
Checkout und Befehle werden im Root des Repositories ausgeführt. Die Anwendung liegt unter src/, die Betriebslogik in planer, compose*.yaml und scripts/.
git clone https://github.com/pfarr-tools/pfarrplaner.git
cd pfarrplaner
Die .env bleibt lokal und wird niemals committed. Lassen Sie ./planer install die Datei aus .env.example erzeugen; ein vorheriges manuelles Kopieren macht die Datei für den Bootstrap zu einer bestehenden Installation und kann Produktionsdefaults wie APP_ENV=production und APP_DEBUG=false verhindern. Vor dem Start müssen mindestens öffentliche URL, Datenbank, Redis, MinIO, Mail und – in Produktion – sichere Passwörter gesetzt sein. Portwerte werden über die .env angepasst; feste Ports gehören nicht in eigene Skripte.
Wichtige Werte sind:
APP_URLfür die öffentliche Adresse,APP_KEYund gegebenenfallsDATABASE_KEY,DB_DATABASE,DB_USERNAME,DB_PASSWORDundDB_ROOT_PASSWORD,REDIS_PASSWORD,AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYundAWS_BUCKET,MAIL_*für den gewählten Mailbetrieb,COMPOSE_PROJECT_NAMEund bei Bedarf die*_PORT-Werte.
Produktiv müssen verpflichtende Variablen gesetzt sein; die Produktions-Compose-Datei bricht bei fehlenden Werten ab. Entwicklungsdefaults sind nur für lokale Entwicklung geeignet.
2.3. 2.1 Befehlsübersicht¶
Der Root-Befehl wählt ohne Unterbefehl den Produktionskontext. Für Entwicklung wird der Kontext immer ausdrücklich mit dev angegeben:
| Bereich | Befehle |
|---|---|
| Produktion | ./planer up, down, restart, status, logs, exec, shell, artisan |
| Entwicklung | ./planer dev up, down, restart, status, logs, exec, shell, artisan |
| Entwicklung prüfen | ./planer dev test, composer, npm, pint, format, format:check, analyse, lint, docs:check, quality |
| Handbücher | ./planer dev manual build, dusk, site, all, deploy, source-publish |
| Produktion vorbereiten | ./planer install bzw. ./planer bootstrap, ./planer build, ./planer release, ./planer update, ./planer migrate legacy |
| Daten und Sicherungen | ./planer backup create, list, verify, restore, prune, check, init; ./planer data |
Unterbefehle und Optionen werden an ./planer weitergereicht. Für die Manual-Befehle ist auch die Kurzform ./planer dev manual:site beziehungsweise die entsprechende manual:*-Variante verfügbar. ./planer dev fresh --force setzt die lokale Entwicklungsdatenbank vollständig zurück und darf nicht gegen eine produktive Umgebung verwendet werden.
2.4. 3. Erstkonfiguration¶
Wählen Sie genau einen Betriebsweg pro Checkout und Compose-Projekt. Für Produktion erzeugt die interaktive Erstkonfiguration die Betriebswerte, fragt Provider, Administrator, Backup-Ziele und Mailmodus ab und kann optional einen bestehenden Datenbestand importieren:
./planer install --prod
./planer bootstrap bleibt dafür ein Alias. Vor einem Import werden Zielumgebung, Datenbankname und Backupquelle geprüft. Ein Produktiv- oder Legacy-Backup darf nicht in eine Testdatenbank importiert werden. Nach der interaktiven Initialisierung startet der Importpfad die benötigten Container, führt Migrationen und roles:sync aus und richtet den initialen Super-Administrator ein.
Für Entwicklung verwenden Sie einen separaten Checkout oder mindestens einen eigenen COMPOSE_PROJECT_NAME und eigene Ports/Volumes:
./planer install --dev
./planer dev up -d --build
./planer dev artisan migrate --force
./planer dev artisan roles:sync
Die PHP-FPM-Prozesse laufen im Entwicklungscontainer als www-data. Die
Artisan-, Composer-, Analyse- und Testbefehle des ./planer-Wrappers werden
deshalb ebenfalls unter diesem Benutzer ausgeführt. So bleiben kompilierte
Blade-Views und andere Laravel-Laufzeitdateien für den Webprozess änderbar.
Direkte Aufrufe über ./planer dev exec müssen bei Bedarf --user www-data
vor dem Dienstnamen setzen.
Der Entwicklungs-Bootstrap legt bewusst keinen Administrator an. Für einen lokalen Administrator verwenden Sie danach den vorgesehenen Artisan-Befehl mit Passwortübergabe über stdin; das Passwort wird nicht als Argument protokolliert:
read -r -s -p 'Passwort: ' PFARRPLANER_ADMIN_PASSWORD; printf '\n'
printf '%s' "$PFARRPLANER_ADMIN_PASSWORD" | ./planer dev exec -T --user www-data app php artisan pfarrplaner:initial-admin \
--email=admin@localhost --first-name=Administrator --last-name=Pfarrplaner \
--password-stdin --must-change-password
unset PFARRPLANER_ADMIN_PASSWORD
Wenn Entwicklungs- und Produktionsinstanz parallel laufen, müssen sie getrennte Checkouts oder mindestens unterschiedliche COMPOSE_PROJECT_NAME-Werte, Host-Ports und Docker-Volumes verwenden. Nie dieselbe .env oder Datenbank für beide Wege verwenden.
Bei der Einrichtung von Restic-Zielen prüft ./planer backup init, ob bereits ein Repository vorhanden ist. Bestehende Backup-Daten werden nur nach der ausdrücklichen Bestätigung j oder ja ersetzt.
2.5. 4. Images bauen und Dienste starten¶
Für lokale Entwicklung startet der zentrale Befehl die PHP-, Web-, Vite-, Infrastruktur- und Hintergrunddienste:
./planer dev up -d --build
./planer dev status
Die Entwicklungsumgebung enthält typischerweise app, web, vite, manual, horizon, scheduler, mariadb, redis, minio, create-buckets, soketi und mailpit. Der backup-Dienst wird nur mit dem Compose-Profil tools aktiviert.
Der produktive Start verwendet das veröffentlichte Image und die Produktions-Compose-Datei:
./planer up -d
./planer status
Bei einem lokalen Produktions- oder Vorabtest kann ein Image zunächst über ./planer build beziehungsweise ./planer build --ref <tag|commit> gebaut werden. Das erzeugte lokale Image muss anschließend mit PFARRPLANER_IMAGE=pfarrplaner-app:<tag> in der Produktions-.env ausgewählt werden; andernfalls verwendet Compose weiterhin das veröffentlichte Standardimage. App, Horizon und Scheduler warten auf die gesunden Infrastrukturabhängigkeiten. Die App wird erst nach einem erfolgreichen Health-Check dem Webserver zugeordnet.
2.6. 5. Dienste und Datenhaltung¶
| Dienst | Aufgabe | Persistenz bzw. Schnittstelle |
|---|---|---|
app |
Laravel-/PHP-Anwendung; in Produktion Octane/Swoole | src/storage in Produktion, Quellcode in Entwicklung |
web |
Caddy als HTTP-/Reverse-Proxy | Caddy-Daten und -Konfiguration |
vite |
Entwicklungsserver für Frontend-Assets | Host-Port aus VITE_PORT |
mariadb |
Anwendungsdatenbank | mariadb_data |
redis |
Cache, Sessions und Queue-Unterstützung | redis_data |
minio |
verbindlicher Objektspeicher für Anhänge und Dateien | minio_data |
horizon |
Queue-Worker | keine eigene Fachdatenpersistenz |
scheduler |
Laravel-Scheduler | keine eigene Fachdatenpersistenz |
soketi |
WebSocket-Broadcasting | keine Fachdatenpersistenz |
mailpit |
lokale Mailprüfung bzw. produktiver Diagnosezugang | in Produktion nur loopback-gebunden, keine Mailzustellung und keine Fachdatenpersistenz |
postfix |
optionales produktives Send-only-Mail-Relay | postfix_queue |
ftp |
FTP-Eingang für die Ablage-API | ftp_inbox, FTP-/Passivports aus .env |
MariaDB, Redis, MinIO und – bei aktiviertem Mailprofil – die Postfix-Warteschlange dürfen bei Container-Neustarts nicht verloren gehen. Anhänge werden nicht ungeprüft in storage/app abgelegt; MinIO ist der verbindliche Dateispeicher.
Der Dienst ftp verwendet die Variablen FTP_USER, FTP_PASSWORD,
FTP_PASV_ADDRESS, FTP_PORT, FTP_PASV_MIN_PORT und FTP_PASV_MAX_PORT.
Das Volume ftp_inbox wird beim FTP-Benutzer eingehängt und parallel als
/var/www/html/storage/inbox in den App-Containern eingebunden. Die
FTP_INBOX_STORAGE_PATH-Konfiguration lautet standardmäßig inbox. Der
Eingang bleibt bewusst vom MinIO-Storage und vom MinIO-/Restic-Backup getrennt.
2.7. 6. Erstprüfung¶
Nach dem Start werden zuerst Containerstatus und Health-Endpunkt geprüft. Die .env wird nicht in die interaktive Shell exportiert; verwenden Sie daher die konkret konfigurierte URL:
./planer status
curl -fsS https://pfarrplaner.example.org/api/health
Für einen lokalen Entwicklungsstart mit dem Standardport lautet die Prüfung beispielsweise:
curl -fsS http://127.0.0.1:8180/api/health
2.8. 6.1 Öffentliche HTTPS-Adresse¶
Die Produktions-Compose-Datei veröffentlicht Caddy absichtlich nur auf 127.0.0.1:${APP_PORT}. DNS und TLS werden deshalb auf dem Host oder einem vorgeschalteten Reverse-Proxy eingerichtet. Bei einem Host-Caddy mit automatischer Zertifikatsverwaltung genügt beispielsweise:
pfarrplaner.example.org {
reverse_proxy 127.0.0.1:8080
}
Setzen Sie APP_URL=https://pfarrplaner.example.org, öffnen Sie in der Firewall nur 80/443 für den vorgeschalteten Proxy und lassen Sie den internen APP_PORT geschlossen. Der mitgelieferte produktive Caddy setzt für Laravel bereits X-Forwarded-Proto=https, X-Forwarded-Host und Port 443. Wenn ein anderer Proxy verwendet wird, müssen diese Forwarded-Header und die Vertrauenskonfiguration gleichwertig gesetzt werden.
Für den Bootstrap werden openssl und Docker benötigt. Bei SSH-basierten Backupzielen sind zusätzlich ssh-keyscan und ssh-keygen auf dem Host erforderlich; bei lokalen oder S3-/Restic-Zielen entfallen diese beiden Werkzeuge.
Danach sind mindestens folgende Funktionen zu prüfen:
- Anmeldung mit dem beim Bootstrap angelegten Administratorkonto.
- Öffnen der Startseite und einer Kalenderansicht.
- Anlegen oder Öffnen eines Gottesdienstes.
- Datei-Upload und Abruf aus MinIO.
- Bericht oder PDF-Ausgabe mit Chromium.
- Queue und Scheduler über Status und Logs.
- Mailversand; in Entwicklung über Mailpit, in Produktion über das aktivierte Mailprofil.
Logs werden kontextbezogen gelesen:
./planer logs app
./planer logs horizon
./planer logs scheduler
2.9. 7. Backups einrichten¶
Vor produktivem Betrieb werden backup.yaml und die geschützten Dateien unter secrets/ außerhalb von Git eingerichtet. Ein vollständiger Satz enthält MariaDB, MinIO-Objekte, Restic-Konfiguration und bei Bedarf die Postfix-Warteschlange.
./planer backup init
./planer backup create
./planer backup verify
Backups benötigen einen Host-Timer oder eine andere verlässliche regelmäßige Ausführung. Ein Restore wird zunächst in ein separates Ziel geschrieben. Das Überschreiben einer produktiven Umgebung erfordert ausdrücklich --apply --yes, ein geprüftes Backup und einen dokumentierten Rückfallweg.
2.10. 8. Sichere Befehlsgrenzen¶
- Entwicklung:
./planer dev ... - Produktion:
./planer ... - Tests ausschließlich mit
./planer dev test; dieser setzt eine isolierte SQLite-In-Memory-Datenbank. ./planer dev exec app php artisan testwird absichtlich blockiert, weil damit die normale Entwicklungsdatenbank gefährdet wäre.- Migrationen und produktive Artisan-Befehle werden erst nach Ziel- und Backup-Prüfung ausgeführt.
Weitere Befehle und der Update-/Rollback-Ablauf stehen im Kapitel zu Deployment und Betrieb. Das ergänzende Administratorhandbuch zur Installation beschreibt den administrativen Ablauf.