DDEV startet für jedes Projekt einen eigenen Satz Container: Web mit nginx und PHP-FPM, eine Datenbank, Mailpit und einen Router, der das Projekt unter https://<projekt>.ddev.site mit gültigem Zertifikat bereitstellt. Auf dem Rechner genügen Docker und ddev. PHP, Composer und Node brauchen Sie auf dem Host nicht, und dort sollen sie auch nicht laufen.
Ein neues Projekt legen ddev config --project-type=symfony --docroot=public und ddev start an, Symfony installiert dann ddev composer create-project symfony/skeleton hinein. In einem bestehenden Repository genügt ddev config in seinem Wurzelverzeichnis.
DDEV ist leicht einzusetzen und leicht zu verbiegen: ein eigenes Skript statt einer Option in config.yaml, ein von Hand gestarteter Container neben dem Projekt, eine Kopie der Webserver-Konfiguration. Hier steht, was DDEV von sich aus kann und wo es sich lohnt, es zu erweitern.
Grundkonfiguration
Tragen Sie PHP-, Datenbank- und Node-Version wie in der Produktion ein, damit jeder Entwickler dieselbe Umgebung hat wie die Produktion.
name: projekt
type: symfony
docroot: public
php_version: "8.5" # wie in der Produktion
webserver_type: nginx-fpm
database:
type: postgres
version: "18" # wie in der Produktion
timezone: Europe/Prague # sonst vom Host übernommen
nodejs_version: "24"
corepack_enable: true
composer_version: "2"
webimage_extra_packages:
- php${DDEV_PHP_VERSION}-imagick
use_dns_when_possible: true
type: symfony installiert die Symfony CLI im Container, ergänzt ddev console als Kurzform für bin/console und schreibt die Verbindungen zu Datenbank und Mailer in .env.local (siehe nächstes Kapitel). Der Typ php macht nichts davon. Geben Sie docroot: public ausdrücklich an.
Füllen Sie timezone immer aus. Ohne sie übernimmt DDEV die Zone vom Host, sodass zwei Entwickler unterschiedliche Umgebungen haben können, ohne es zu wissen. Datumswerte und geplante Aufgaben verhalten sich dann anders als in der Produktion.
ddev config erzeugt eine config.yaml mit Hunderten Zeilen auskommentierter Hilfe. Löschen Sie sie. Die eigenen Einstellungen gehen darin unter, und im Diff ist schlechter zu sehen, was sich geändert hat. Die Hilfe steht in der Dokumentation und in ddev config --help.
Vor einer zu alten DDEV-Version bei Kollegen schützt ddev_version_constraint: '>= 1.25' (die konkrete Version richtet sich nach den Funktionen, die das Projekt nutzt). Ein älteres DDEV startet das Projekt dann nicht und sagt, warum.
Was ins Git gehört
Ins Repository gehören config.yaml, docker-compose.*.yaml, commands/, web-build/, db-build/, php/, nginx/ und die Dateien der Add-ons. Generierte Dateien und persönliche Einstellungen ignoriert DDEV selbst über seine eigene .ddev/.gitignore, darunter config.local.yaml und .ddev/.env.local.
config.local.yaml ist der Ort für alles, was sich von Rechner zu Rechner unterscheidet: eine Adresse für den Zugriff aus dem lokalen Netz, ein anderer Name einer Projektkopie, ein abgeschalteter Hook. Die Werte werden mit config.yaml zusammengeführt. Wenn Sie sie ersetzen statt ergänzen wollen (Hostname-Listen, Hooks), schreiben Sie override_config: true in die Datei.
Umgebungsvariablen und .env
Beim Typ symfony schreibt DDEV bei jedem ddev start die Verbindungen zu Datenbank und Mailer in .env.local (im composer_root): DATABASE_URL, MAILER_DSN=smtp://127.0.0.1:1025, MAILER_WEB_URL mit der Adresse von Mailpit und einige Hilfsschlüssel. Ein frischer Klon funktioniert so nach ddev start ohne manuelle Einrichtung.
Daraus folgen drei Regeln:
- Schreiben Sie keine eigene
DATABASE_URLoderMAILER_DSNin.env.local, DDEV überschreibt sie beim nächsten Start. Die übrigen Zeilen der Datei lässt es in Ruhe, Secrets und persönliche Abweichungen gehören weiterhin dorthin. - Eine Anleitung „tragen Sie
MAILER_DSNin.env.localein“ ist überflüssig, DDEV erledigt das selbst. - Wer
.env.localselbst verwalten will, setztdisable_settings_management: trueund trägt die Werte ein, zum Beispiel mitddev dotenv set .env.local --database-url=….
Andere Werte für die Entwicklung, die nicht geheim sind (DEFAULT_URI=https://projekt.ddev.site, Adressen lokaler Services), versionieren Sie am besten in .env.dev.
.env.local wird in der Umgebung test nicht geladen, die Werte von DDEV sehen Tests also nicht. Die Adresse der Testdatenbank gehört in .env.test:
# .env.test
DATABASE_URL="postgresql://db:db@db:5432/db?serverVersion=18&charset=utf8"
web_environment schlägt die .env-Dateien. web_environment in config.yaml und .ddev/.env.web setzen Umgebungsvariablen für den ganzen Web-Container, unabhängig von APP_ENV. Es sind echte Umgebungsvariablen, und Symfony überschreibt sie nicht mit Werten aus den .env*-Dateien. Steht dort DATABASE_URL, bekommen sie auch die Tests, und der Wert aus .env.test greift nicht. Eine Änderung in .env.local wirkt ebenfalls nicht, der Wert lässt sich nur in config.yaml und mit ddev restart ändern.
In web_environment gehört deshalb nur, was jeder Prozess im Container unabhängig von der Symfony-Umgebung braucht, etwa COMPOSER_AUTH. Werte, die sich zwischen dev und test unterscheiden, gehören in .env.dev und .env.test.
Was DDEV zusätzlich mitbringt
Neben Webserver und Datenbank hat DDEV eine Reihe von Werkzeugen, die eigene Lösungen überflüssig machen. Man muss nur von ihnen wissen.
Mailpit fängt alle Mails des Projekts ab. Es läuft direkt im Web-Container auf 127.0.0.1:1025, die Oberfläche öffnet ddev mailpit. MAILER_DSN richtet DDEV selbst in .env.local darauf aus. Wer das über disable_settings_management abgeschaltet hat, muss es von Hand eintragen, sonst verwirft das Standard-null://null aus dem Recipe die Mails. Zu jeder Nachricht zeigt es Quelltext, Anhänge und den Reiter HTML Check, der auflistet, welche HTML- und CSS-Funktionen einzelne Mailprogramme nicht unterstützen. Für E-Mail-Templates ist das eine schnellere Prüfung als das Versenden an echte Postfächer. Ein eigener Mailpit-Container ist ein überflüssiges zweites Exemplar.
Import und Export der Datenbank ohne Kenntnis des Datenbank-Clients:
ddev import-db --file=dump.sql.gz # auch .sql, .zip, .tar.gz, .zst
gzip -dc dump.sql.gz | ddev import-db # von der Standardeingabe
ddev import-db --database=zweite --file=… # in eine andere Datenbank
ddev import-db --no-drop --file=… # ohne vorhandene Daten zu löschen
ddev export-db --file=/tmp/db.sql.zst # Komprimierung nach Dateiendung
ddev psql # oder ddev mysql
Für eine teilweise Übertragung (nur einige Tabellen) genügt es, den Dump an ddev psql weiterzuleiten. Über docker exec ddev-<projekt>-db müssen Sie nicht gehen.
Snapshots sind schneller als ein Dump, weil sie die Dateien der Datenbank kopieren: ddev snapshot --name vor-import, zurück mit ddev snapshot restore vor-import (oder --latest), Übersicht mit ddev snapshot --list. Legen Sie vor jeder riskanten Operation einen an: Massenimport, doctrine:fixtures:load ohne --append, manueller Eingriff in die Daten, Test einer Migration. Sie liegen in .ddev/db_snapshots/ und kommen nicht ins Git. Wiederherstellen lässt sich ein Snapshot nur in dieselbe Art und Version der Datenbank.
- Einen Snapshot namens
seedverwendet DDEV automatisch für jede neue Datenbank des Projekts, etwa nachddev delete. ddev start --reset-databasebeginnt mit einer leeren Datenbank und sichert die bisherige vorher als Snapshot.
Datenbank-Client mit grafischer Oberfläche. Einen auf dem Rechner installierten Client startet DDEV direkt mit der Verbindung zum aktuellen Port: ddev dbeaver auf allen Systemen, ddev tableplus auf macOS und in WSL2. Den Befehl bietet es nur an, wenn es die Anwendung am üblichen Ort findet. Wer einen anderen Client nutzt, setzt einen festen host_db_port. Ohne Installation auf dem Rechner hilft das webbasierte Adminer als Add-on (ddev add-on get ddev/ddev-adminer, dann ddev adminer).
ddev pull lädt Datenbank und Dateien über einen Provider in .ddev/providers/ vom Hosting herunter. Einen Produktions-Dump bereitet heute aber meist CI oder ein Deployer vor, und der wird dann mit ddev import-db eingespielt. ddev auth ssh reicht die Schlüssel des Hosts an den Container weiter, etwa für Composer mit privaten Repositories über SSH.
Produktionsdaten enthalten in der Regel personenbezogene Daten. Auf den Rechner eines Entwicklers gehört nur, was die Arbeit erfordert: Inhalte ohne Benutzer (pg_dump --table=…) oder ein Dump, der personenbezogene Daten unterwegs anonymisiert.
Hochgeladene Dateien. Die Verzeichnisse aus upload_dirs füllt ddev import-files.
Debugging und Performance:
ddev xdebug onundoffschalten Xdebug ohne Neustart um,ddev xdebug statuszeigt den Zustand. Eingeschaltet verlangsamt es jeden Request, deshalb keinxdebug_enabled: truein der Konfiguration. Mappen Sie in der IDE das ganze Projekt auf/var/www/html, nicht nur das Docroot. Wenn sich der Debugger nicht verbindet, sagtddev utility xdebug-diagnose, warum.ddev xhprofundddev xhguischalten das Profiling und seine Oberfläche ein. Für die Frage „warum ist diese Seite langsam“ reicht das ohne Blackfire.ddev logs -fverfolgt die Ausgabe von Webserver, PHP und Daemons,ddev logs -s dbdie der Datenbank.
Übersicht und Zugriff:
ddev describelistet Adressen, Ports und Services des Projekts auf,ddev launchöffnet die Website,ddev tuieine interaktive Übersicht.ddev sharestellt das Projekt unter einer öffentlichen Adresse bereit, standardmäßig über ngrok, mit--provider=cloudflaredohne Konto. Praktisch für eine Vorführung beim Kunden oder den Test eines Webhooks. Die Adresse ist öffentlich, solange der Tunnel läuft.- Das Plugin DDEV Integration für PhpStorm richtet PHP-Interpreter, Datenbank und Node nach dem laufenden Projekt ein.
Kleinigkeiten, die Zeit sparen:
- Der Composer-Cache wird zwischen Projekten geteilt, eine zweite Installation derselben Pakete kommt von der Festplatte.
.ddev/homeadditions/wird ins Home-Verzeichnis im Container kopiert. Praktisch für gemeinsame Aliase des ganzen Teams (.bash_aliases). Persönliches (.gitconfig, History) gehört nach~/.ddev/homeadditions/auf dem Host.ddev composer,ddev npm,ddev yarn,ddev phpundddev consolestarten die Werkzeuge im Container. PHP und Node brauchen Sie auf dem Host nicht, und die Versionen laufen so nicht auseinander.
PHP-Extensions und das Web-Image
Debian-Pakete, typischerweise PHP-Extensions, werden in config.yaml ergänzt. Die Variable hält das Paket bei der gewählten PHP-Version:
webimage_extra_packages:
- php${DDEV_PHP_VERSION}-imagick
- php${DDEV_PHP_VERSION}-pcov
- chromium
- chromium-driver
Für komplexere Anpassungen gibt es .ddev/web-build/Dockerfile.<zweck>. Jede Anpassung in eine eigene Datei, damit erkennbar ist, warum sie da ist. Das eignet sich zum Beispiel für Einstellungen nur für PHP-FPM (siehe Limits) oder dafür, PHP-Pakete auf das neueste Patch-Release zu heben. Das Web-Image kann ein älteres PHP-Patch-Release enthalten als das Paket-Repository, und roave/security-advisories blockiert dann composer update:
# .ddev/web-build/Dockerfile.php-upgrade
RUN apt-get update \
&& apt-get install -y --only-upgrade $(dpkg-query -W -f='${db:Status-Status} ${Package}\n' "php${DDEV_PHP_VERSION}-*" | awk '$1 == "installed" { print $2 }') \
&& rm -rf /var/lib/apt/lists/*
Die Änderung wirkt nach ddev restart. Wenn das Image ohne Cache gebaut werden muss, ddev utility rebuild.
Das Web-Image hat nur wenige Locales, Tschechisch ist nicht dabei. Wer setlocale() oder strftime mit cs_CZ braucht, ergänzt in webimage_extra_packages das Paket locales-all. Intl und ICU brauchen das nicht.
Datenbank
Dieselbe Art und Hauptversion der Datenbank wie in der Produktion, sonst zeigen sich Unterschiede in SQL, Sortierung oder JSON-Funktionen erst nach dem Deployment.
Datenbank-Extensions (pgvector, PostGIS, ein Wörterbuch für die Volltextsuche) werden über .ddev/db-build/Dockerfile auf dem Image installiert, aus dem DDEV die Datenbank baut:
# .ddev/db-build/Dockerfile
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
"postgresql-${PG_MAJOR}-pgvector" "postgresql-${PG_MAJOR}-postgis-3" \
&& rm -rf /var/lib/apt/lists/*
Das Image liefert nur die Binaries. CREATE EXTENSION IF NOT EXISTS gehört in eine Doctrine-Migration, damit die Datenbank in DDEV, in Tests und in der Produktion auf demselben Weg entsteht. Ein Skript in docker-entrypoint-initdb.d läuft nur beim ersten Anlegen der Datenbank und in der Produktion gar nicht.
Der Build-Kontext ist das Verzeichnis .ddev/db-build/. Dateien, die mit dem Produktions-Dockerfile geteilt werden (ein Skript, eine Stoppwortliste), müssen dort als Kopie liegen, ein Symlink nach außen funktioniert nicht. Die Übereinstimmung der Kopien prüft ein einzeiliges diff in der CI.
Sortierung und Locale. PostgreSQL entsteht in DDEV mit einer glibc-Locale, in der diakritische Zeichen mit dem Grundbuchstaben zusammenfallen. Legt die Produktion den Cluster mit ICU und einer bestimmten Locale an, sortiert sie anders, und der Unterschied zeigt sich erst in der Produktion. Abhilfe schafft das Überschreiben einer Variable des Datenbank-Containers:
# .ddev/docker-compose.postgres-locale.yaml
services:
db:
environment:
POSTGRES_INITDB_ARGS: "--locale-provider=icu --icu-locale=cs-CZ"
Das gilt nur beim ersten Anlegen des Clusters. Eine bestehende Datenbank braucht ddev delete -O und ein erneutes Einspielen der Daten. Prüfung: ddev psql -U db -d db -tAc "select datlocprovider, datlocale from pg_database where datname = current_database()" muss i|cs-CZ liefern.
Eine Testdatenbank neben der Entwicklungsdatenbank. Doctrine hängt an den Namen ein Suffix an:
# config/packages/doctrine.yaml
when@test:
doctrine:
dbal:
dbname_suffix: '_test%env(default::TEST_TOKEN)%'
Einmal anlegen (ddev console doctrine:database:create --env=test --if-not-exists) und nach jeder Migration aktualisieren (ddev console doctrine:migrations:migrate --env=test -n). TEST_TOKEN trennt die Datenbanken paralleler ParaTest-Prozesse.
Der Datenbank-Port auf dem Host ändert sich mit jedem Neustart. Für den Client in der IDE zeigt ihn ddev describe, oder host_db_port in config.local.yaml legt ihn fest, für jedes Projekt einen anderen.
Import, Export und Snapshots stehen im Kapitel Was DDEV zusätzlich mitbringt.
Vite und HMR
Vite läuft im Container, der Browser auf dem Host. Damit HMR funktioniert, muss der Port durch den Router gehen und Vite muss die öffentliche Adresse des Projekts kennen:
# .ddev/config.yaml
web_extra_exposed_ports:
- name: vite
container_port: 5173
http_port: 5172
https_port: 5173
Füllen Sie alle drei Felder aus, ohne https_port startet der Router nicht.
// vite.config.js
import { resolve } from 'node:path'
const origin = `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`
export default defineConfig({
server: {
host: '0.0.0.0',
port: 5173,
strictPort: true,
origin,
cors: { origin: /https?:\/\/([A-Za-z0-9\-.]+)?(\.ddev\.site)(?::\d+)?$/ },
watch: {
ignored: [resolve('vendor/**'), resolve('var/**')],
},
},
})
- Nehmen Sie die Adresse aus
DDEV_PRIMARY_URL_WITHOUT_PORT, nicht fest eingetragen. Die Konfiguration funktioniert dann auch in einer Kopie des Projekts unter anderem Namen. - Vite überwacht das ganze Projektverzeichnis.
vendor/undvar/erschöpfen das Limit überwachter Dateien, deshalb nehmen Sie sie aus. Die Pfade müssen absolut sein: Das Projekt liegt im Container unter/var/www/html, das Muster/var/würde also alles ausschließen. - Änderungen an Twig oder PHP kennt Vite nicht. Ein kurzes Plugin, das bei ihrer Änderung
full-reloadsendet, erspart das manuelle Neuladen der Seite.
Starten lässt sich Vite von Hand (ddev npm run dev, die Ausgabe haben Sie vor Augen) oder automatisch mit dem Projekt über web_extra_daemons. Die Ausgabe des Daemons zeigt ddev logs -s web.
Messenger und Scheduler
Queue-Consumer und Scheduler sind lang laufende Prozesse. DDEV kann sie mit dem Projekt starten:
web_extra_daemons:
- name: messenger
command: 'while true; do bin/console messenger:consume async scheduler_default --time-limit=3600 --memory-limit=256M -vv; done'
directory: /var/www/html
Der Daemon hält den Code geladen. Nach einer Änderung am Handler läuft die alte Version, bis Sie ihn neu starten (ddev exec supervisorctl restart 'webextradaemons:*'). Möglichkeiten:
- Ihn über die Symfony CLI starten, die ihn bei Codeänderungen selbst neu startet:
symfony run --watch=config,src,templates,vendor bin/console messenger:consume async -vvalscommanddes Daemons. - Nachrichten in
devaufsync://leiten und den Consumer nur zum Debuggen der Queues starten (ddev console messenger:consume async -vv).
Scheduler-Zustand und Locks brauchen einen gemeinsamen Speicher (Redis, Datenbank). Ohne ihn beginnt der Scheduler nach einem Neustart bei „jetzt“ und holt verpasste Läufe nicht nach. In der Entwicklung ist das in Ordnung, man sollte es nur wissen.
Weitere Services
Zuerst ein Add-on. ddev add-on get ddev/ddev-redis (ebenso OpenSearch, Elasticsearch, RabbitMQ, Solr, Adminer und weitere) fügt einen Service hinzu, der mit dem Projekt startet und stoppt und den jemand pflegt. Anpassungen des Add-ons in eine eigene Datei, etwa .ddev/docker-compose.redis_extra.yaml. Dateien des Add-ons mit #ddev-generated bearbeiten Sie nicht, das nächste Update würde sie überschreiben.
Ein eigener Service, wenn es kein Add-on gibt:
# .ddev/docker-compose.overpass.yaml
services:
overpass:
container_name: ddev-${DDEV_SITENAME}-overpass
image: wiktorn/overpass-api
restart: "no"
expose:
- "80"
environment:
- VIRTUAL_HOST=${DDEV_HOSTNAME}
- HTTP_EXPOSE=12344:80
- HTTPS_EXPOSE=12345:80
volumes:
- overpass_data:/db
volumes:
overpass_data:
container_namenach der Konventionddev-${DDEV_SITENAME}-…. Die Labelscom.ddev.site-nameundcom.ddev.approotergänzt DDEV selbst. Ältere Versionen brauchten sie von Hand, sonst ließddev stopden Container weiterlaufen.- Die Weboberfläche des Services stellen Sie über den Router bereit (
VIRTUAL_HOST,HTTP_EXPOSE,HTTPS_EXPOSE), nicht überports. Der Router bewältigt mehrere Projekte gleichzeitig ohne Portkonflikte. portsnur für einen Nicht-HTTP-Service, den ein Prozess auf dem Host braucht, und immer mit127.0.0.1:am Anfang. Ohne das veröffentlicht Docker den Port auf allen Interfaces, und seine Regeln umgehen sogar die Firewall des Hosts. Ein Redis ohne Passwort könnte dann jeder im selben Netz lesen und beschreiben.- Geben Sie dem Volume mit Daten, deren Aufbereitung lange dauert (ein Kartenindex, ein Import von Codelisten), einen Namen. Es übersteht
ddev restartund lässt sich in eine andere Kopie des Projekts kopieren.
Mailpit, Xdebug, XHProf und das Teilen nach außen hat DDEV bereits (siehe Was DDEV zusätzlich mitbringt). Fügen Sie sie nicht noch einmal hinzu.
Ein Service auf dem Host. Ein Prozess, der auf dem Host läuft (zum Beispiel Ollama wegen der GPU), ist aus dem Container über host.docker.internal erreichbar. Er muss auch außerhalb von Loopback lauschen (OLLAMA_HOST=0.0.0.0).
Das Frontend in DDEV, nicht daneben. Eine eigenständige Frontend-Anwendung (Next.js, Nuxt) lässt sich als weiterer Eintrag in web_extra_daemons mit eigenem web_extra_exposed_ports starten. Wenn Sie sie wegen localhost:3000 in einer OAuth-redirect_uri auf dem Host laufen lassen, haben Sie zwei Umgebungen, nach außen veröffentlichte Ports und eine doppelte Anleitung. Einfacher ist es, die redirect_uri unter der Adresse aus DDEV zu registrieren.
Übereinstimmung mit der Produktion
DDEV hat Standardwerte für die Entwicklung: memory_limit 1024M, upload_max_filesize und post_max_size 100M, max_execution_time 600 s, nginx ohne Limit für die Request-Größe. Ein Request, den die Produktion ablehnt, geht lokal durch, und den Zweig mit der Fehlermeldung probiert niemand aus. Setzen Sie die Limits der Produktion deshalb auch in DDEV. PHP liest jede Datei .ddev/php/*.ini, nginx jede .ddev/nginx/*.conf, den Dateinamen wählen Sie selbst. Wirksam werden sie nach ddev restart. Das Beispiel verwendet nur die Standardwerte von PHP, ersetzen Sie sie im Projekt durch die Werte seiner Produktion:
; .ddev/php/limits.ini — Beispiel, gilt für CLI und FPM
; Standardwerte von PHP, durch die Werte der Produktion ersetzen
upload_max_filesize = 2M
post_max_size = 8M
max_execution_time = 30
# .ddev/nginx/limits.conf — Beispiel, DDEV fügt sie am Ende des server-Blocks ein
# wie post_max_size in PHP
client_max_body_size 8m;
- Die ganze
nginx_full/nginx-site.confwegen einer Direktive zu übernehmen, heißt, sich um eine Konfiguration zu kümmern, die sonst DDEV pflegt. .ddev/php/*.inigilt für CLI und FPM gleichzeitig. Die CLI kann aber höhere Limits brauchen, etwamemory_limitfür PHPStan oder Batch-Importe. Einstellungen nur für FPM backen Sie ins Image:
# .ddev/web-build/Dockerfile.fpm-limits
RUN printf 'memory_limit = 256M\n' > /etc/php/${DDEV_PHP_VERSION}/fpm/conf.d/zz-limits.ini
- Die Übereinstimmung der Werte zwischen
.ddev/, dem Produktions-Dockerfile und dem Caddyfile kann ein einfacher Test prüfen, der die Dateien liest und vergleicht. Achten Sie auf die Einheiten:30MBin Caddy sind 30 × 1000²,30Min PHP und30min nginx 30 × 1024².
Eine andere Runtime in der Produktion. Läuft die Produktion auf FrankenPHP im Worker-Modus, zeigt DDEV mit nginx und PHP-FPM keinen Zustand, der zwischen Requests durchsickert. Halten Sie die Regeln für den Worker-Modus (kein Zustand in Services, ResetInterface) von Anfang an ein. Lokal lässt sich der Worker-Modus mit dem Add-on ddev/ddev-frankenphp ausprobieren, das selbst auf webserver_type: generic umschaltet. Das hat seinen Preis:
- Der Worker-Modus wird in
FRANKENPHP_CONFIGeingeschaltet. Der Kernel überlebt dann zwischen Requests, eine Änderung insrc/oderconfig/wirkt also erst nach einem Neustart des Workers (ddev exec supervisorctl restart 'webextradaemons:*'). Den Neustart bei Änderungen übernimmt die Direktivewatch, nur mit Pfaden zu den Quellen. Das Standardmuster überwacht das ganze Projekt einschließlichvar/cache/, wohin Symfony zur Laufzeit PHP-Dateien schreibt.
# .ddev/docker-compose.frankenphp_extra.yaml
services:
web:
environment:
FRANKENPHP_CONFIG: |
worker {
file ./public/index.php
watch ./src/**/*.php
watch ./config/**/*.{php,yaml}
watch ./.env*
}
- PHP ist ein ZTS-Build aus einem anderen Repository, erst ab Version 8.2. Extensions werden als
php-zts-…installiert, die dort fehlenden werden über PIE kompiliert. - CLI und Web teilen sich eine PHP-Konfiguration. Limits nur für das Web gehören in
php_iniinFRANKENPHP_CONFIG. Statt.ddev/nginx/wird das Caddyfile angepasst.
Die Standardumgebung des Teams bleibt deshalb FPM, und der Worker-Modus wird gezielt eingeschaltet, wenn ein durchsickernder Zustand vermutet wird.
Client-IP. DDEV übergibt PHP HTTPS=on, Symfony erzeugt also auch ohne Proxy-Einstellung Adressen mit https://. REMOTE_ADDR ist aber die Adresse des Routers. Wenn es auf die IP ankommt (Rate Limiter, Logs), setzen Sie trusted_proxies genauso wie hinter dem Proxy in der Produktion.
Das Produktions-Image baut ein eigenes Dockerfile. DDEV ist eine Entwicklungsumgebung, keine Vorlage für die Produktion. Was zwischen beiden übereinstimmen muss, sollte an beiden Stellen stehen und durch einen Test geprüft werden.
Hooks und eigene Befehle
post-start läuft bei jedem ddev start. Dorthin gehört nur, ohne das der aktuelle Code nicht läuft, und es muss idempotent sein:
hooks:
post-start:
- composer: install
- exec: bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration
Übersetzungen herunterladen, Codelisten aus einer externen Quelle importieren oder Assets bauen verlangsamt den Start im Hook auf Minuten und scheitert, wenn das Netz ausfällt. Ein fehlgeschlagener Hook hält den Start standardmäßig nicht auf (fail_on_hook_fail: false), der Fehler geht also leicht unter. Solche Schritte gehören in einen eigenen Befehl.
Eigene Befehle sind Skripte in .ddev/commands/web/ (laufen im Container) oder .ddev/commands/host/ (auf dem Host). Der Kopf ist die Hilfe für ddev help:
#!/usr/bin/env bash
## Description: Richtet das Projekt nach dem Klonen ein: Abhängigkeiten, Datenbank, Codelisten, Übersetzungen
## Usage: setup
## Example: "ddev setup"
set -euo pipefail
composer install
bin/console doctrine:migrations:migrate -n --allow-no-migration
bin/console app:codelist:import
bin/console translation:pull crowdin --force
npm ci && npm run build
Geeignete Kandidaten: ddev setup nach dem Klonen, ddev test-db zum Anlegen und Migrieren der Testdatenbank, ddev e2e für End-to-End-Tests. Das Makefile ruft dann ddev exec oder eigene Befehle auf und muss die Pfade im Container nicht kennen.
Ein Skript in .ddev/web-entrypoint.d/*.sh wird beim Start des Containers noch vor PHP-FPM eingelesen (sourced). Es läuft in der Shell des Startskripts, setzen Sie also keine eigenen set-Optionen und denken Sie daran, dass exit 1 den Start des ganzen Containers beendet. Das meiste, was dort geschrieben wird, erledigt web-build/Dockerfile sauberer.
Tests
PHPUnit läuft im Container: ddev exec vendor/bin/phpunit. Die Abdeckung misst PCOV aus webimage_extra_packages, schneller als Xdebug. Beschränken Sie es auf den Quellcode, sonst durchläuft es auch vendor/ und node_modules/:
; .ddev/php/pcov.ini
pcov.directory = /var/www/html/src
Schalten Sie Xdebug nur zum Debuggen ein (ddev xdebug on, ddev xdebug off). Eingeschaltet verlangsamt es jeden Request.
End-to-End-Tests mit Panther laufen komplett in DDEV:
- Chromium und chromedriver aus
webimage_extra_packages. Chrome im Container brauchtPANTHER_NO_SANDBOX=1undPANTHER_CHROME_ARGUMENTS="--disable-dev-shm-usage"in.env.test. - Eine zweite Adresse des Projekts über
additional_hostnames: [test.projekt]und ein eigenerserver-Block in.ddev/nginx_full/test-env.conf, der PHP-FPMfastcgi_param APP_ENV testübergibt. Die Hauptadresse dient weiter der Entwicklung, die Testadresse läuft gegen die Testdatenbank mit gefälschten Zahlungsgateways und Uhren. - Test-Doubles müssen in der Konfiguration der Umgebung
testverdrahtet sein.self::getContainer()->set()im Test ändert nur den Container des Tests, nicht den, der die Requests des Browsers bedient. Den Zustand zwischen Prozessen geben sie über Dateien weiter. - Vor der Testsuite einige Requests an die Testadresse schicken, damit der Container in allen FPM-Workern im OPcache liegt. Sonst scheitern die ersten Tests zufällig an einem Timeout.
- Das Ganze in einen Befehl
ddev e2epacken.
Mehrere Projektkopien nebeneinander
Zwei Branches gleichzeitig in Arbeit, das Frontend einer neuen Funktion gegen ihre Backend-Version, ein Review eines fremden Branches, ein Agent oder eine lange Testsuite neben der Arbeit. Branches in einem Verzeichnis zu wechseln heißt, jedes Mal auch die Datenbank zu wechseln, weil jeder Branch andere Migrationen hat. Besser ist es, jeden Branch in einem eigenen Verzeichnis (git worktree) als eigenes DDEV-Projekt mit eigener Datenbank zu haben. Zwei Kopien mit demselben name streiten sich um die Container.
Name aus dem Verzeichnis. Wenn config.yaml keinen name hat, heißt das Projekt wie sein Verzeichnis. Jeder Klon und jeder git worktree hat dann eigene Container, eine eigene Adresse und Datenbank ohne weitere Einrichtung. Damit ddev config den Namen nicht selbst in die Datei schreibt, setzen Sie ddev config global --omit-project-name-by-default=true. Wenn der Name in config.yaml bleiben muss, überschreibt ihn die Kopie in config.local.yaml:
override_config: true
name: projekt2
additional_hostnames: [test.projekt2]
additional_fqdns: []
Nichts mit Name oder Port fest eingetragen. Kopien kommen sich nur dann nicht in die Quere, wenn die gemeinsame Konfiguration nichts enthält, was in jeder Kopie anders sein muss:
- Die Adresse des Projekts im Code und in
vite.config.js→ die UmgebungsvariablenDDEV_PRIMARY_URLundDDEV_PRIMARY_URL_WITHOUT_PORT. DDEV setzt sie im Web-Container, in eigenen Befehlen und beim Einsetzen in Compose-Dateien. In der Shell des Hosts gibt es sie nicht. additional_hostnamesmit dem Projektnamen und feste Ports (host_db_port,host_https_port) →config.local.yaml, sonst vergibt die Ports DDEV.- Der auf dem Host veröffentlichte Port eines eigenen Services → eine Variable mit Standardwert in der Compose-Datei und ein anderer Wert für jede Kopie in einer per Gitignore ausgeschlossenen
.ddev/.env.*.local. Eine Datei, deren Name keinem Service entspricht, wird nur in die Compose-Dateien eingesetzt und gelangt nicht in die Container:
# .ddev/docker-compose.redis_extra.yaml
services:
redis:
ports:
- "127.0.0.1:${REDIS_HOST_PORT:-6379}:6379"
ddev dotenv set .ddev/.env.ports.local --redis-host-port 6380
Das Frontend mit seiner Backend-Version. Ein Frontend in einem Branch braucht das Backend aus demselben Branch, nicht das, das gerade im Hauptverzeichnis läuft.
- Frontend und Backend in einem Repository: Der Worktree enthält beides in der richtigen Version. Läuft das Frontend wie Vite über
web_extra_daemonsundweb_extra_exposed_portsin DDEV, findet es das Backend seiner Kopie überDDEV_PRIMARY_URLund Services wie Redis über den Servicenamen (redis:6379) ohne veröffentlichten Port. Die Kopien haben nichts, worum sie sich streiten, und eine neue braucht keine Einrichtung. - Ein Frontend auf dem Host sieht die Variablen von DDEV nicht, jede Kopie muss also einen anderen Port für die Services veröffentlichen, die das Frontend braucht, und seine
.env.localmuss auf Adresse und Ports des Backends seiner Kopie zeigen. Das funktioniert, aber jede Kopie bedeutet manuelle Einrichtung an zwei Stellen. Wenn das Frontend durch eine fest registrierte Adresse an den Host gebunden ist, etwa eine OAuth-redirect_uriauflocalhost:3000, lohnt es sich, sie in den lokalen Daten ausDDEV_PRIMARY_URLabzuleiten und das Frontend in DDEV zu verlegen. - Frontend und Backend in getrennten Repositories: den Worktree des Backends nach dem Branch benennen, damit er eine vorhersehbare Adresse hat (
https://<branch>-api.ddev.site), und das Frontend dieses Branches darauf ausrichten.
Daten für eine neue Kopie:
- Die ignorierten Dateien kopieren (
.env.local,auth.json, hochgeladene Daten). - Die Datenbank per Snapshot übertragen:
ddev snapshot --name copyin der Quelle, die Datei aus.ddev/db_snapshots/verschieben und in der Kopieddev snapshot restore copy. - Benannte Volumes mit aufwendigen Daten über
docker run --rm -v quelle:/from:ro -v ziel:/to … cp -a /from/. /to/kopieren.
Das alles gehört in ein einziges Skript, das die Kopie jedes Mal gleich anlegt. Nicht genutzte Kopien hält ddev stop an, alles auf einmal ddev poweroff.
macOS und Windows
Unter Linux und in WSL2 gelangen die Dateien direkt in den Container. Auf macOS und Windows synchronisiert DDEV standardmäßig über Mutagen:
- Verzeichnisse, die nicht synchronisiert werden sollen (hochgeladene Daten,
node_modules), gehören inupload_dirs, danachddev mutagen reset. - Git auf dem Host ausführen. Nach einem Branch-Wechsel hilft
ddev mutagen sync, am besten aus einem Git-Hookpost-checkout. performance_modenicht committen. Er gehört in die globale Konfiguration oder inconfig.local.yaml, ein Kollege auf einem anderen System will ihn nicht.- In WSL2 muss das Projekt im Linux-Dateisystem liegen, nicht unter
/mnt/c. Der Geschwindigkeitsunterschied liegt bei einer Größenordnung.
Zugriff aus dem lokalen Netz und Teilen nach außen
Standardmäßig ist das Projekt nur vom eigenen Rechner aus erreichbar. Von einem anderen Gerät im Netz, etwa einem Telefon, Tablet oder dem Rechner eines Kollegen, kommen Sie so darauf:
- Der Router muss auf allen Interfaces lauschen:
ddev config global --router-bind-all-interfaces=true. Die Firewall des Rechners muss die Ports 80 und 443 durchlassen. - Eine Adresse mit der IP des Rechners über nip.io in
config.local.yaml(die IP unterscheidet sich von Rechner zu Rechner):
additional_fqdns:
- projekt.192.168.0.10.nip.io
- Manche Router und DNS-Filter verwerfen Antworten mit einer lokalen IP (Schutz vor DNS-Rebinding). Dann hilft ein Eintrag in der
hosts-Datei des anderen Geräts oder ein anderer DNS-Server. - Das andere Gerät kennt die Zertifizierungsstelle von mkcert nicht, HTTPS meldet also einen Fehler. Entweder installieren Sie sie dort, oder Sie testen über HTTP, sofern die Anwendung HTTPS nicht erzwingt.
- Außerhalb des lokalen Netzes hilft
ddev share.
Häufige Workarounds und der bessere Weg
- Ein eigener Container mit Mailpit → das eingebaute Mailpit und
smtp://127.0.0.1:1025. - Redis von Hand in Compose geschrieben →
ddev add-on get ddev/ddev-redisund Anpassungen in einer_extra-Datei. - Eine Kopie von
nginx-site.confwegen einer Direktive → eine Datei in.ddev/nginx/. - Eine fest eingetragene Projektadresse in
vite.config.js→DDEV_PRIMARY_URL_WITHOUT_PORT. docker exec ddev-projekt-db psqlin Anleitungen →ddev psql,ddev import-db,ddev snapshot.- Der Datenbank-Port in die Dokumentation abgeschrieben →
ddev describeoderhost_db_port. - Build und Downloads von externen Diensten in
post-start→ ein eigener Befehlddev setup. DATABASE_URLoderMAILER_DSNvon Hand in.env.localoder inweb_environment→ DDEV überlassen, für Tests.env.test.- Ein Frontend auf dem Host neben DDEV →
web_extra_daemonsundweb_extra_exposed_ports. - Ein Init-SQL-Skript für
CREATE EXTENSION→ eine Doctrine-Migration. - Der Hinweis „nach dem Pullen
ddev restartausführen“ im README → eine Gewohnheit nach jeder Änderung in.ddev/. DDEV meldet selbst beim Start, dass es eine eigene Konfiguration gefunden hat, und erinnert an den Neustart. Was genau aus.ddev/gilt und in welcher Reihenfolge, listetddev utility check-custom-configauf.