DDEV runs a separate set of containers for each project: web with nginx and PHP-FPM, a database, Mailpit and a router that serves the project at https://<project>.ddev.site with a valid certificate. All you need on your machine is Docker and ddev. You don't need PHP, Composer or Node on the host, and they shouldn't run there either.
A new project is set up with ddev config --project-type=symfony --docroot=public and ddev start, and Symfony is then installed into it with ddev composer create-project symfony/skeleton. In an existing repository, running ddev config in its root is enough.
DDEV is easy to start with and easy to bend: a custom script instead of an option in config.yaml, a container started by hand next to the project, a copy of the web server configuration. Here is what DDEV can do on its own and where it pays to extend it.
Configuration basics
Set the PHP, database and Node versions to match production, so that every developer has the same environment as production.
name: project
type: symfony
docroot: public
php_version: "8.5" # same as production
webserver_type: nginx-fpm
database:
type: postgres
version: "18" # same as production
timezone: Europe/Prague # otherwise taken from the host
nodejs_version: "24"
corepack_enable: true
composer_version: "2"
webimage_extra_packages:
- php${DDEV_PHP_VERSION}-imagick
use_dns_when_possible: true
type: symfony installs the Symfony CLI in the container, adds ddev console as a shortcut for bin/console and writes the database and mailer connections to .env.local (see the next section). The php type does none of this. Set docroot: public explicitly.
Always fill in timezone. Without it, DDEV takes the zone from the host, so two developers can have different environments without knowing it. Dates and scheduled tasks then behave differently than in production.
ddev config generates a config.yaml with hundreds of lines of commented-out help. Delete it. Your own settings get lost in it and diffs are harder to read. The help is in the documentation and in ddev config --help.
ddev_version_constraint: '>= 1.25' protects against colleagues running a DDEV version that is too old (set the actual version according to the features the project uses). An older DDEV then refuses to start the project and says why.
What goes into git
The repository should contain config.yaml, docker-compose.*.yaml, commands/, web-build/, db-build/, php/, nginx/ and the add-on files. DDEV ignores generated files and personal settings on its own through its .ddev/.gitignore, including config.local.yaml and .ddev/.env.local.
config.local.yaml is the place for what differs from machine to machine: an address for access from the local network, a different name for a project copy, a disabled hook. Its values are merged with config.yaml. When you need to replace them rather than add to them (hostname lists, hooks), put override_config: true in the file.
Environment variables and .env
For the symfony type, DDEV writes the database and mailer connections to .env.local (in composer_root) on every ddev start: DATABASE_URL, MAILER_DSN=smtp://127.0.0.1:1025, MAILER_WEB_URL with the Mailpit address and a few helper keys. A fresh clone works after ddev start with no manual setup.
That leads to three rules:
- Don't write your own
DATABASE_URLorMAILER_DSNto.env.local, DDEV overwrites it on the next start. It leaves the other lines of the file alone, so secrets and personal overrides still belong there. - Instructions like "add
MAILER_DSNto.env.local" are unnecessary, DDEV does it itself. - If you want to manage
.env.localyourself, setdisable_settings_management: trueand write the values, for example withddev dotenv set .env.local --database-url=….
Other development values that aren't secret (DEFAULT_URI=https://project.ddev.site, addresses of local services) are worth versioning in .env.dev.
.env.local isn't loaded in the test environment, so tests don't see the values from DDEV. The test database address belongs in .env.test:
# .env.test
DATABASE_URL="postgresql://db:db@db:5432/db?serverVersion=18&charset=utf8"
web_environment wins over the .env files. web_environment in config.yaml and .ddev/.env.web set environment variables for the whole web container, regardless of APP_ENV. They are real environment variables, and Symfony doesn't override them with values from the .env* files. If DATABASE_URL is there, tests get it too and the value from .env.test doesn't apply. A change in .env.local won't take effect either, the value can only be changed in config.yaml followed by ddev restart.
So web_environment should only hold what every process in the container needs regardless of the Symfony environment, such as COMPOSER_AUTH. Values that differ between dev and test belong in .env.dev and .env.test.
What else DDEV brings
Besides the web server and database, DDEV comes with a set of tools that make building your own pointless. You just need to know about them.
Mailpit catches all mail from the project. It runs right in the web container on 127.0.0.1:1025, and ddev mailpit opens its interface. DDEV points MAILER_DSN at it in .env.local itself. If you turned that off with disable_settings_management, you have to set it by hand, otherwise the recipe's default null://null throws the mail away. For each message it shows the source, attachments and an HTML Check tab that lists which HTML and CSS features individual mail clients don't support. For email templates, that is a quicker check than sending to real inboxes. A separate Mailpit container is a pointless second copy.
Database import and export without knowing the database client:
ddev import-db --file=dump.sql.gz # also .sql, .zip, .tar.gz, .zst
gzip -dc dump.sql.gz | ddev import-db # from standard input
ddev import-db --database=other --file=… # into another database
ddev import-db --no-drop --file=… # without deleting existing data
ddev export-db --file=/tmp/db.sql.zst # compression by file extension
ddev psql # or ddev mysql
For a partial transfer (just a few tables), pipe the dump into ddev psql. There is no need to go through docker exec ddev-<project>-db.
Snapshots are faster than a dump because they copy the database files: ddev snapshot --name before-import, back with ddev snapshot restore before-import (or --latest), list with ddev snapshot --list. Take one before every risky operation: a bulk import, doctrine:fixtures:load without --append, a manual data fix, a migration test. They live in .ddev/db_snapshots/ and don't go into git. A snapshot can only be restored to the same database type and version.
- A snapshot named
seedis used automatically by DDEV for every new database of the project, for example afterddev delete. ddev start --reset-databasestarts with an empty database and saves the old one as a snapshot first.
Database client with a graphical interface. DDEV launches a client installed on your machine already connected to the current port: ddev dbeaver on all systems, ddev tableplus on macOS and in WSL2. It only offers the command when it finds the application in its usual location. If you use a different client, set a fixed host_db_port. Without installing anything on your machine, there is the web-based Adminer as an add-on (ddev add-on get ddev/ddev-adminer, then ddev adminer).
ddev pull downloads the database and files from a hosting provider through a provider file in .ddev/providers/. These days, though, a production dump is usually prepared by CI or a deployer and then loaded with ddev import-db. ddev auth ssh passes keys from the host to the container, for example for Composer with private repositories over SSH.
Production data usually contains personal data. A developer's machine should only get what the work requires: content without users (pg_dump --table=…), or a dump that anonymizes personal data along the way.
Uploaded files. ddev import-files fills the directories listed in upload_dirs.
Debugging and performance:
ddev xdebug onandofftoggle Xdebug without a restart,ddev xdebug statusshows its state. When on, it slows down every request, so don't usexdebug_enabled: truein the config. In the IDE, map the whole project to/var/www/html, not just the docroot. When the debugger doesn't connect,ddev utility xdebug-diagnosetells you why.ddev xhprofandddev xhguiturn on profiling and its interface. For "why is this page slow" questions, that is enough without Blackfire.ddev logs -ffollows the output of the web server, PHP and daemons,ddev logs -s dbthat of the database.
Overview and access:
ddev describelists the project's addresses, ports and services,ddev launchopens the site,ddev tuian interactive overview.ddev shareexposes the project at a public address, by default through ngrok, with--provider=cloudflaredwithout an account. Useful for showing work to a client or testing a webhook. The address is public as long as the tunnel runs.- The DDEV Integration plugin for PhpStorm sets up the PHP interpreter, database and Node from the running project.
Small things that save time:
- The Composer cache is shared across projects, so a second install of the same packages comes from disk.
.ddev/homeadditions/is copied into the home directory in the container. Useful for aliases shared by the whole team (.bash_aliases). Personal things (.gitconfig, history) belong in~/.ddev/homeadditions/on the host.ddev composer,ddev npm,ddev yarn,ddev phpandddev consolerun the tools in the container. You don't need PHP or Node on the host, so versions can't drift apart.
PHP extensions and the web image
Debian packages, typically PHP extensions, are added in config.yaml. The variable keeps the package in line with the chosen PHP version:
webimage_extra_packages:
- php${DDEV_PHP_VERSION}-imagick
- php${DDEV_PHP_VERSION}-pcov
- chromium
- chromium-driver
For more complex changes, there is .ddev/web-build/Dockerfile.<purpose>. Put each change in its own file so it's clear why it's there. It is useful, for example, for FPM-only settings (see Limits) or for bringing PHP packages up to the latest patch release. The web image can ship an older PHP patch release than the package repository, and roave/security-advisories then blocks 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/*
The change takes effect after ddev restart. To build the image without cache, use ddev utility rebuild.
The web image only has a few locales, and Czech isn't one of them. If you need setlocale() or strftime with cs_CZ, add the locales-all package to webimage_extra_packages. Intl and ICU don't need it.
Database
Use the same database type and major version as production, otherwise differences in SQL, collation or JSON functions only show up after deployment.
Database extensions (pgvector, PostGIS, a full-text dictionary) are installed through .ddev/db-build/Dockerfile on top of the image DDEV builds the database from:
# .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/*
The image only provides the binaries. CREATE EXTENSION IF NOT EXISTS belongs in a Doctrine migration, so the database is set up the same way in DDEV, in tests and in production. A script in docker-entrypoint-initdb.d runs only when the database is first created, and not at all in production.
The build context is the .ddev/db-build/ directory. Files shared with the production Dockerfile (a script, a stop word list) have to be copies there, a symlink pointing outside doesn't work. A one-line diff in CI keeps the copies in sync.
Collation and locale. PostgreSQL in DDEV is created with a glibc locale, where accented characters sort together with the base letter. When production creates the cluster with ICU and a specific locale, it sorts differently, and the difference only shows up in production. Overriding a variable of the database container helps:
# .ddev/docker-compose.postgres-locale.yaml
services:
db:
environment:
POSTGRES_INITDB_ARGS: "--locale-provider=icu --icu-locale=cs-CZ"
This only applies when the cluster is first created. An existing database needs ddev delete -O and the data loaded again. To check: ddev psql -U db -d db -tAc "select datlocprovider, datlocale from pg_database where datname = current_database()" should return i|cs-CZ.
A test database next to the development one. Doctrine adds a suffix to the name:
# config/packages/doctrine.yaml
when@test:
doctrine:
dbal:
dbname_suffix: '_test%env(default::TEST_TOKEN)%'
Create it once (ddev console doctrine:database:create --env=test --if-not-exists) and update it after every migration (ddev console doctrine:migrations:migrate --env=test -n). TEST_TOKEN keeps the databases of parallel ParaTest processes apart.
The database port on the host changes with every restart. For a client in the IDE, ddev describe shows it, or host_db_port in config.local.yaml fixes it, a different one for each project.
Import, export and snapshots are covered in What else DDEV brings.
Vite and HMR
Vite runs in the container, the browser on the host. For HMR to work, the port has to go through the router and Vite has to know the project's public address:
# .ddev/config.yaml
web_extra_exposed_ports:
- name: vite
container_port: 5173
http_port: 5172
https_port: 5173
Fill in all three fields, without https_port the router won't start.
// 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/**')],
},
},
})
- Take the address from
DDEV_PRIMARY_URL_WITHOUT_PORT, don't hard-code it. The configuration then also works in a copy of the project under a different name. - Vite watches the whole project root.
vendor/andvar/exhaust the limit on watched files, so leave them out. The paths have to be absolute: the project lives under/var/www/htmlin the container, so the pattern/var/would exclude everything. - Vite doesn't know about changes to Twig or PHP. A short plugin that sends
full-reloadwhen they change saves you from refreshing the page by hand.
You can start it by hand (ddev npm run dev, with the output in front of you) or automatically with the project through web_extra_daemons. ddev logs -s web shows the daemon's output.
Messenger and Scheduler
The queue consumer and the scheduler are long-running processes. DDEV can start them with the project:
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
The daemon keeps the code loaded. After you change a handler, the old version runs until you restart it (ddev exec supervisorctl restart 'webextradaemons:*'). Options:
- Run it through the Symfony CLI, which restarts it when the code changes:
symfony run --watch=config,src,templates,vendor bin/console messenger:consume async -vvas the daemon'scommand. - Route messages to
sync://indevand run the consumer only when debugging queues (ddev console messenger:consume async -vv).
The scheduler state and locks need shared storage (Redis, a database). Without it, the scheduler starts from "now" after a restart and doesn't catch up on missed runs. That is fine in development, just be aware of it.
Other services
Add-on first. ddev add-on get ddev/ddev-redis (and OpenSearch, Elasticsearch, RabbitMQ, Solr, Adminer and more) adds a service that starts and stops with the project and that someone maintains. Put your add-on adjustments in a file of your own, for example .ddev/docker-compose.redis_extra.yaml. Don't edit add-on files marked #ddev-generated, the next update would overwrite them.
Your own service, when there is no add-on:
# .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_namefollowing theddev-${DDEV_SITENAME}-…convention. DDEV adds thecom.ddev.site-nameandcom.ddev.approotlabels itself. Older versions needed them by hand, otherwiseddev stopleft the container running.- Expose the service's web interface through the router (
VIRTUAL_HOST,HTTP_EXPOSE,HTTPS_EXPOSE), not throughports. The router handles several projects at once without port conflicts. - Use
portsonly for a non-HTTP service that a process on the host needs, and always with127.0.0.1:at the start. Without it, Docker publishes the port on all interfaces and its rules even bypass the host firewall. A Redis without a password could then be read and written by anyone on the same network. - Name the volume for data that takes a long time to prepare (a map index, an import of code lists). It survives
ddev restartand can be copied to another copy of the project.
DDEV already has Mailpit, Xdebug, XHProf and public sharing (see What else DDEV brings). Don't add them again.
A service on the host. A process running on the host (for example Ollama, because of the GPU) is reachable from the container via host.docker.internal. It has to listen beyond loopback too (OLLAMA_HOST=0.0.0.0).
The frontend in DDEV, not next to it. A separate frontend application (Next.js, Nuxt) can run as another entry in web_extra_daemons with its own web_extra_exposed_ports. If you run it on the host because of localhost:3000 in an OAuth redirect_uri, you end up with two environments, ports published to the outside and two sets of instructions. It is simpler to register the redirect_uri at the DDEV address.
Matching production
DDEV has development defaults: memory_limit 1024M, upload_max_filesize and post_max_size 100M, max_execution_time 600 s, nginx without a request size limit. A request that production rejects will pass locally, and nobody ever tries the code path with the error message. So set the production limits in DDEV too. PHP reads every .ddev/php/*.ini file and nginx every .ddev/nginx/*.conf file, the file name is up to you. They take effect after ddev restart. The sample is only an example with PHP's default values, replace them with the values from your project's production:
; .ddev/php/limits.ini — example, applies to both CLI and FPM
; PHP defaults, replace them with the production values
upload_max_filesize = 2M
post_max_size = 8M
max_execution_time = 30
# .ddev/nginx/limits.conf — example, DDEV includes it at the end of the server block
# same as post_max_size in PHP
client_max_body_size 8m;
- Taking over the whole
nginx_full/nginx-site.conffor a single directive means maintaining configuration that DDEV would otherwise maintain for you. .ddev/php/*.iniapplies to CLI and FPM at once. The CLI, however, may need higher limits, for examplememory_limitfor PHPStan or batch imports. Bake FPM-only settings into the image:
# .ddev/web-build/Dockerfile.fpm-limits
RUN printf 'memory_limit = 256M\n' > /etc/php/${DDEV_PHP_VERSION}/fpm/conf.d/zz-limits.ini
- A plain test that reads the files and compares them can check that the values in
.ddev/, the production Dockerfile and the Caddyfile match. Mind the units:30MBin Caddy is 30 × 1000²,30Min PHP and30min nginx are 30 × 1024².
A different runtime in production. When production runs on FrankenPHP in worker mode, DDEV with nginx and PHP-FPM won't show state leaking between requests. Follow the worker mode rules (no state in services, ResetInterface) from the start. You can try worker mode locally with the ddev/ddev-frankenphp add-on, which switches to webserver_type: generic itself. It comes at a price:
- Worker mode is turned on in
FRANKENPHP_CONFIG. The kernel then survives between requests, so a change insrc/orconfig/only takes effect after the worker restarts (ddev exec supervisorctl restart 'webextradaemons:*'). Thewatchdirective restarts it on change, but only give it paths to source files. The default pattern watches the whole project, includingvar/cache/, where Symfony writes PHP files at runtime.
# .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 is a ZTS build from a different repository, 8.2 and later only. Extensions are installed as
php-zts-…, and those not in it are compiled with PIE. - CLI and web share a single PHP configuration. Web-only limits go into
php_iniinFRANKENPHP_CONFIG. Instead of.ddev/nginx/, you edit the Caddyfile.
That is why FPM stays the team's default environment, and worker mode is turned on deliberately when state leaking is suspected.
Client IP. DDEV passes HTTPS=on to PHP, so Symfony generates https:// URLs even without a proxy configuration. REMOTE_ADDR, however, is the router's address. When the IP matters (rate limiter, logs), set trusted_proxies the same way as behind a proxy in production.
The production image is built by its own Dockerfile. DDEV is a development environment, not a template for production. Whatever has to match between them should be written in both places and checked by a test.
Hooks and custom commands
post-start runs on every ddev start. Only what the current code can't run without belongs there, and it has to be idempotent:
hooks:
post-start:
- composer: install
- exec: bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration
Pulling translations, importing code lists from an external source or building assets in a hook slows the start down to minutes and fails when the network is down. By default, a failing hook doesn't stop the start (fail_on_hook_fail: false), so the error is easy to miss. Such steps belong in a custom command.
Custom commands are scripts in .ddev/commands/web/ (run in the container) or .ddev/commands/host/ (run on the host). The header is the help text for ddev help:
#!/usr/bin/env bash
## Description: Sets up the project after cloning: dependencies, database, code lists, translations
## 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
Good candidates: ddev setup after cloning, ddev test-db to create and migrate the test database, ddev e2e for end-to-end tests. The Makefile then calls ddev exec or custom commands and doesn't need to know paths inside the container.
A script in .ddev/web-entrypoint.d/*.sh is sourced when the container starts, before PHP-FPM. It runs in the shell of the startup script, so don't set your own set options, and remember that exit 1 ends the start of the whole container. Most of what people put there is done more cleanly by web-build/Dockerfile.
Tests
PHPUnit runs in the container: ddev exec vendor/bin/phpunit. Coverage is measured by PCOV from webimage_extra_packages, which is faster than Xdebug. Limit it to the source code, otherwise it also goes through vendor/ and node_modules/:
; .ddev/php/pcov.ini
pcov.directory = /var/www/html/src
Turn Xdebug on only for debugging (ddev xdebug on, ddev xdebug off). When on, it slows down every request.
End-to-end tests with Panther run entirely in DDEV:
- Chromium and chromedriver from
webimage_extra_packages. Chrome in the container needsPANTHER_NO_SANDBOX=1andPANTHER_CHROME_ARGUMENTS="--disable-dev-shm-usage"in.env.test. - A second project address via
additional_hostnames: [test.project]and a separateserverblock in.ddev/nginx_full/test-env.confthat passesfastcgi_param APP_ENV testto PHP-FPM. The main address keeps serving development, the test one runs against the test database with fake payment gateways and clocks. - Test doubles have to be wired up in the
testenvironment configuration.self::getContainer()->set()in a test only changes the test's container, not the one serving the browser's requests. Processes pass state to each other through files. - Warm up with a few requests to the test address before the suite, so the container is loaded into OPcache in all FPM workers. Otherwise the first tests randomly fail on a timeout.
- Wrap it all in a
ddev e2ecommand.
Multiple project copies side by side
Two branches in progress at once, the frontend of a new feature against its own backend version, reviewing someone else's branch, an agent, or a long test suite running alongside your work. Switching branches in a single directory means switching the database every time too, because each branch has different migrations. It is better to have each branch in its own directory (git worktree) as a separate DDEV project with its own database. Two copies with the same name fight over the containers.
Name from the directory. When config.yaml has no name, the project is named after its directory. Every clone and git worktree then gets its own containers, address and database with no further setup. To stop ddev config from writing the name into the file, set ddev config global --omit-project-name-by-default=true. When the name has to stay in config.yaml, the copy overrides it in config.local.yaml:
override_config: true
name: project2
additional_hostnames: [test.project2]
additional_fqdns: []
Nothing hard-coded with a name or port. Copies only stay out of each other's way when the shared configuration holds nothing that has to differ in each copy:
- The project address in code and in
vite.config.js→ theDDEV_PRIMARY_URLandDDEV_PRIMARY_URL_WITHOUT_PORTenvironment variables. DDEV sets them in the web container, in custom commands and when filling in compose files. They aren't in the host shell. additional_hostnamescontaining the project name and fixed ports (host_db_port,host_https_port) →config.local.yaml, otherwise DDEV assigns the ports.- The host port of your own service → a variable with a default value in the compose file and a different value for each copy in a gitignored
.ddev/.env.*.local. A file whose name doesn't match any service is only used to fill in the compose files and doesn't reach the containers:
# .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
The frontend with its own backend version. A frontend in a branch needs the backend from the same branch, not the one that happens to be running in the main directory.
- Frontend and backend in one repository: the worktree contains both in the right version. When the frontend runs in DDEV through
web_extra_daemonsandweb_extra_exposed_ports, like Vite, it finds the backend of its own copy viaDDEV_PRIMARY_URLand services such as Redis via the service name (redis:6379) without a published port. The copies have nothing to fight over and a new one needs no setup. - A frontend on the host doesn't see the DDEV variables, so each copy has to publish a different port for the services the frontend needs, and its
.env.localhas to point at the address and ports of its own copy's backend. It works, but every copy means manual setup in two places. When the frontend is tied to the host by a hard-coded registered address, such as an OAuthredirect_urionlocalhost:3000, it is worth deriving it fromDDEV_PRIMARY_URLin the local data and moving the frontend into DDEV. - Frontend and backend in separate repositories: name the backend worktree after the branch so it has a predictable address (
https://<branch>-api.ddev.site), and point the frontend of that branch at it.
Data for a new copy:
- Copy the ignored files (
.env.local,auth.json, uploaded data). - Transfer the database with a snapshot:
ddev snapshot --name copyin the source, move the file from.ddev/db_snapshots/and runddev snapshot restore copyin the copy. - Copy named volumes with expensive data via
docker run --rm -v source:/from:ro -v target:/to … cp -a /from/. /to/.
All of this belongs in a single script that sets up a copy the same way every time. Stop copies you aren't using with ddev stop, everything at once with ddev poweroff.
macOS and Windows
On Linux and in WSL2, files go into the container directly. On macOS and Windows, DDEV syncs them through Mutagen by default:
- Put directories that shouldn't be synced (uploaded data,
node_modules) inupload_dirs, then runddev mutagen reset. - Run git on the host. After switching branches,
ddev mutagen synchelps, ideally from apost-checkoutgit hook. - Don't commit
performance_mode. It belongs in the global configuration orconfig.local.yaml, a colleague on a different system doesn't want it. - In WSL2, the project has to be on the Linux file system, not on
/mnt/c. The speed difference is an order of magnitude.
Access from the local network and sharing outside
By default, the project is only reachable from your own machine. From another device on the network, such as a phone, a tablet or a colleague's computer, you get to it like this:
- The router has to listen on all interfaces:
ddev config global --router-bind-all-interfaces=true. The machine's firewall has to allow ports 80 and 443. - An address with the machine's IP via nip.io goes into
config.local.yaml(the IP differs from machine to machine):
additional_fqdns:
- project.192.168.0.10.nip.io
- Some routers and DNS filters drop answers with a local IP (DNS rebinding protection). A
hostsentry on the other device or a different DNS server helps. - The other device doesn't know the mkcert certificate authority, so HTTPS will report an error. Either install it there, or test over HTTP if the application doesn't enforce HTTPS.
- Outside the local network,
ddev sharehelps.
Common workarounds and the better way
- A custom Mailpit container → the built-in Mailpit and
smtp://127.0.0.1:1025. - Redis written by hand in compose →
ddev add-on get ddev/ddev-redisand adjustments in an_extrafile. - A copy of
nginx-site.conffor a single directive → a file in.ddev/nginx/. - A hard-coded project address in
vite.config.js→DDEV_PRIMARY_URL_WITHOUT_PORT. docker exec ddev-project-db psqlin instructions →ddev psql,ddev import-db,ddev snapshot.- The database port copied into documentation →
ddev describeorhost_db_port. - Builds and downloads from external services in
post-start→ a customddev setupcommand. DATABASE_URLorMAILER_DSNby hand in.env.localor inweb_environment→ leave it to DDEV,.env.testfor tests.- A frontend on the host next to DDEV →
web_extra_daemonsandweb_extra_exposed_ports. - An init SQL script for
CREATE EXTENSION→ a Doctrine migration. - A "run
ddev restartafter pulling changes" note in the README → a habit after every change in.ddev/. DDEV itself reports on start that it found custom configuration and reminds you to restart.ddev utility check-custom-configlists exactly what in.ddev/applies and in what order.