Lokale Entwicklung

Lokal läuft jede Anwendung als eigenes DDEV-Projekt. Ausführlichere, ältere Hinweise (Suche, Ollama, Pimcore-Dump) stehen in Lokales Setup.

Voraussetzungen

• Docker (Docker Desktop, OrbStack o. ä.)
• DDEV ab 1.25
• Bun für die JavaScript-Projekte
• Zugriff auf das Git-Repository

Projekte

Ordner	DDEV-Name	Adresse
admin	matev	https://matev.ddev.site:33001 (APP_URL), außerdem admin.matev.ddev.site
cms	matev-cms	https://matev-cms.ddev.site:33001
staging	matev-staging	https://matev-staging.ddev.site:33005
b2b	matev-b2b	b2b.matev.ddev.site, Ports 33006/33007
storybook	matev-storybook	Ports 33008/33009
docs	matev-docs	Ports 33010/33011

Die genauen Hostnamen und Ports stehen in <projekt>/.ddev/config.yaml; ddev describe im jeweiligen Ordner zeigt sie an.

Alle auf einmal:

./ddev-all.sh start     # auch: stop, restart, status, urls, list
./ddev-all.sh start admin cms staging

PIM (admin) einrichten

cd admin
ddev start                         # composer/bun install, Migrationen, Such-Setup laufen im post-start-Hook
cp .env.example .env               # nur beim ersten Mal
ddev exec php artisan key:generate # nur beim ersten Mal
ddev exec php artisan db:seed

DatabaseSeeder ist idempotent und legt an: Rollen und Rechte, Taxonomie-Grundgerüst, Feld-Templates, Bildformate, den Mandanten matev. Demo-Katalogdaten nur mit SEED_DEMO_PIM=true.

Im admin-Projekt läuft außerdem ein Queue-Worker als DDEV-Daemon (queue:work --queue=default,imports). Bildformate und Importe brauchen ihn.

Lokale Konten

Im Repository stehen keine Benutzer und keine Passwörter. Lokale Konten kommen aus einer Datei, die Git ignoriert:

cp admin/database/seeders/local-users.example.json admin/database/seeders/local-users.json
# Datei bearbeiten: eigene E-Mail und ein eigenes lokales Passwort eintragen
ddev exec php artisan db:seed --class=LocalUserSeeder

Format (local-users.example.json):

[
  {
    "email": "admin@example.test",
    "password": "set-your-own-local-password",
    "first_name": "Local",
    "last_name": "Admin",
    "roles": ["super_admin"],
    "organizations": ["matev"]
  }
]

LocalUserSeeder:

• läuft nur, wenn APP_ENV=local ist (DatabaseSeeder ruft ihn nur dann auf),
• legt Konten per E-Mail an, falls es sie noch nicht gibt, mit gehashtem Passwort, aktiv, Sprache Deutsch, verifiziert,
• setzt Rollen und Mandanten nur bei neu angelegten Konten,
• warnt, wenn die Datei fehlt, und gibt nie Passwörter aus.

admin/database/seeders/local-users.json steht in der .gitignore im Wurzelverzeichnis. Committen Sie die Datei nie, auch nicht umbenannt.

Auf dem Server gibt es diesen Mechanismus nicht. Dort legt ein Admin Konten im PIM an und lädt die Personen ein.

API-Token lokal

Am einfachsten im PIM unter Systemverwaltung → API-Tokens. Für Kirby und Nuxt das Profil „Content-CMS“ wählen und den Token in die jeweilige config.local.yaml eintragen (siehe unten).

Kirby (cms) und Website (staging)

cd cms && ddev start
cd staging && ddev start

Kirby liest keine .env-Datei. Geheimnisse für Kirby und Nuxt stehen lokal in den DDEV-Dateien

• cms/.ddev/config.local.yaml
• staging/.ddev/config.local.yaml

als web_environment-Einträge, z. B. CONTENT_API_URL, CONTENT_API_TOKEN, CONTENT_API_VERIFY_TLS=false, PREVIEW_SECRET, KIRBY_API_USERNAME/KIRBY_API_PASSWORD.

config.local.yaml ist nicht über die Wurzel-.gitignore geschützt

DDEV schließt config.local.yaml über die .ddev/.gitignore aus, die es beim ersten ddev start selbst erzeugt. In einem frischen Klon oder einer Worktree ohne diesen Lauf fehlt sie. Prüfen Sie vor jedem Commit mit git status, dass keine config.local.yaml auftaucht. Dateirechte 0600.

Das Kirby-Panel legt beim ersten Aufruf ein Admin-Konto über den Einrichtungsassistenten an.

Häufige Stolpersteine

• Falsche Datenbank: Die PIM-Anwendung nutzt lokal nicht zwingend die DDEV-Standarddatenbank db. Maßgeblich ist DB_DATABASE in admin/.env.
• Selbst signierte Zertifikate: Kirby → PIM lokal mit CONTENT_API_VERIFY_TLS=false.
• Bilder fehlen: Queue-Worker läuft nicht, oder die Bildformate wurden noch nicht erzeugt (Mediathek → Bildformate → „Formate neu generieren“).