Deployment

Ausgeliefert wird mit Deployer (deploy.php im Wurzelverzeichnis). Es gibt kein Container-Registry: Deployer kopiert den Code per rsync auf den Server und baut dort die Images. Die Server-Seite (Stacks, Caddy, Volumes) beschreibt Deployment (Betrieb) ausführlicher.

Aufruf

Aus dem Wurzelverzeichnis des Haupt-Checkouts:

admin/vendor/bin/dep deploy:preflight production   # nur prüfen: SSH und ~/stacks/apps
admin/vendor/bin/dep deploy:admin production       # nur das PIM
admin/vendor/bin/dep deploy production             # admin, cms, b2b, docs, staging, storybook

Verwenden Sie admin/vendor/bin/dep, nicht ein global installiertes dep: so läuft die Version aus admin/composer.lock.

Die Hosts heißen production und staging und zeigen auf die SSH-Aliasse matev-deploy bzw. matev-staging-deploy. Benutzer, Schlüssel, Port und IP stehen nur in Ihrer ~/.ssh/config, nicht im Repository.

Ablauf je Anwendung

1. Preflight (einmal je Host): SSH im Batch-Modus, Ordner ~/stacks/apps vorhanden.
2. rsync -az --delete von <app>/ nach /var/www/<app>/ auf dem Server.
3. Für b2b, staging, storybook: zusätzlich design-system/ nach <app>/.design-system/.
4. docker compose build <dienst> && docker compose up -d <dienst> in ~/stacks/apps, plus Begleitdienste.
5. Nachbefehle per docker compose exec -T. Schlägt einer fehl, bricht der Deploy ab.

Ausgeschlossen vom rsync

Für	Ausgeschlossen
alle	.git, .ddev, .idea, .playwright-mcp, node_modules, vendor, .env, auth.json, *.log
Laravel (admin, b2b)	zusätzlich storage, bootstrap/cache, import
cms	content, media, site/accounts, site/sessions, Caches und Logs
docs	.vitepress/dist, .vitepress/cache, backups
staging	.output, .nuxt

Für admin wird resources/views/vendor/ ausdrücklich mitkopiert: dort liegt das eigene Mail-Layout.

Daten auf dem Server (Datenbank, storage/ mit den Mediathek-Dateien, Kirby-Inhalte, .env) berührt der Deploy nicht.

Nachbefehle für admin

php artisan migrate --force
php artisan shield:generate --all --panel=admin --option=permissions
php artisan db:seed --force --class=DatabaseSeeder
php artisan optimize:clear
php artisan filament:assets
php artisan filament:optimize
php artisan queue:restart

Danach werden admin-queue und admin-scheduler neu gestartet, damit sie den neuen Code laden.

• Migrationen laufen bei jedem Deploy. Schreiben Sie sie so, dass sie auf Produktionsdaten funktionieren, und mit einem down(), das wirklich zurückgeht.
• DatabaseSeeder läuft ebenfalls bei jedem Deploy. Er muss idempotent bleiben. Er legt keine Benutzer an (außer lokal über LocalUserSeeder).

Für b2b: migrate --force, optimize:clear, portal:sync-pim-accounts.

admin-scheduler

Der Container admin-scheduler (gleiches Image wie admin) führt php artisan schedule:work aus, also alles aus admin/routes/console.php: Protokoll-Archiv, Synonym-Vorschläge, Aufräumen der Suchen und des Papierkorbs (siehe Architektur).

• Er ist in home/bengel/stacks/apps/docker-compose.yml definiert, mit derselben Umgebung und denselben Volumes wie admin.
• Deployer synchronisiert die Compose-Datei nicht. Änderungen daran kopieren Sie von Hand auf den Server (~/stacks/apps/docker-compose.yml) und starten mit docker compose up -d.
• Nach Änderungen an /var/www/admin/.env: docker compose up -d --force-recreate admin admin-queue admin-scheduler. Ein einfacher Neustart reicht nicht (Octane und Worker halten die Konfiguration, und die .env ist als einzelne Datei eingebunden).

Nur aus dem Haupt-Checkout deployen

deploy.php nimmt sein eigenes Verzeichnis als Quelle und rsynct mit --delete. Alles, was auf dem Server liegt, aber im lokalen Baum fehlt, wird gelöscht.

Git-ignorierte Dateien, die nur im Haupt-Checkout existieren, fehlen in jeder Git-Worktree und jedem frischen Klon. Für cms sind das unter anderem der komplette Kirby-Kern (kirby/) und das Plugin zero-one/: Ein Testlauf aus einer Worktree hätte rund 4.700 Dateien auf dem Server gelöscht.

Deshalb:

1. Branch in den Haupt-Checkout holen.
2. Vorher prüfen, was rsync löschen würde, z. B.

   rsync -n -az --delete --exclude-from=<…> cms/ <ssh-alias>:/var/www/cms/ | grep '^deleting'

3. Erst dann deployen.

Wer aus einem anderen Baum deployen muss, stellt vorher sicher, dass alle ignorierten Dateien dort vorhanden sind (Kirby-Kern, Plugins, vendor wird ohnehin ausgeschlossen). Mehr dazu in Layout-Umstellung.

CI

Woodpecker (.woodpecker.yml) testet alle Branches. Nur bei Push auf main läuft der Schritt deploy-production, der denselben Befehl admin/vendor/bin/dep deploy production ausführt.

Checkliste

• [ ] Tests grün (php artisan test --compact)
• [ ] Migrationen lokal hin und zurück geprüft
• [ ] Neue Umgebungsvariablen in admin/.env.example dokumentiert und auf dem Server in /var/www/admin/.env gesetzt
• [ ] Änderungen an docker-compose.yml von Hand übertragen
• [ ] Aus dem Haupt-Checkout, deploy:preflight erfolgreich
• [ ] Nach dem Deploy: Anmeldung im PIM, GET /api/v1/taxonomies, Website-Startseite