Skip to content
iD-SIGN
Contact us

Local Symfony development in DDEV

DDEV gets a Symfony project running with a single command. Here is how to set it up so that every developer has the same versions of PHP, the database, Node and extensions as production. Also where services, daemons and limits belong and which of its features save you from writing your own scripts.

24 min readpublished 11/2026

In this article 16 chapters
  1. Configuration basics
  2. What goes into git
  3. Environment variables and .env
  4. What else DDEV brings
  5. PHP extensions and the web image
  6. Database
  7. Vite and HMR
  8. Messenger and Scheduler
  9. Other services
  10. Matching production
  11. Hooks and custom commands
  12. Tests
  13. Multiple project copies side by side
  14. macOS and Windows
  15. Access from the local network and sharing outside
  16. Common workarounds and the better way

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.

yaml
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_URL or MAILER_DSN to .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_DSN to .env.local" are unnecessary, DDEV does it itself.
  • If you want to manage .env.local yourself, set disable_settings_management: true and write the values, for example with ddev 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:

bash
# .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:

bash
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 seed is used automatically by DDEV for every new database of the project, for example after ddev delete.
  • ddev start --reset-database starts 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 on and off toggle Xdebug without a restart, ddev xdebug status shows its state. When on, it slows down every request, so don't use xdebug_enabled: true in 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-diagnose tells you why.
  • ddev xhprof and ddev xhgui turn on profiling and its interface. For "why is this page slow" questions, that is enough without Blackfire.
  • ddev logs -f follows the output of the web server, PHP and daemons, ddev logs -s db that of the database.

Overview and access:

  • ddev describe lists the project's addresses, ports and services, ddev launch opens the site, ddev tui an interactive overview.
  • ddev share exposes the project at a public address, by default through ngrok, with --provider=cloudflared without 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 php and ddev console run 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:

yaml
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:

dockerfile
# .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:

dockerfile
# .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:

yaml
# .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:

yaml
# 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:

yaml
# .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.

javascript
// 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/ and var/ exhaust the limit on watched files, so leave them out. The paths have to be absolute: the project lives under /var/www/html in 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-reload when 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:

yaml
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 -vv as the daemon's command.
  • Route messages to sync:// in dev and 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:

yaml
# .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_name following the ddev-${DDEV_SITENAME}-… convention. DDEV adds the com.ddev.site-name and com.ddev.approot labels itself. Older versions needed them by hand, otherwise ddev stop left the container running.
  • Expose the service's web interface through the router (VIRTUAL_HOST, HTTP_EXPOSE, HTTPS_EXPOSE), not through ports. The router handles several projects at once without port conflicts.
  • Use ports only for a non-HTTP service that a process on the host needs, and always with 127.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 restart and 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:

bash
; .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
nginx
# .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.conf for a single directive means maintaining configuration that DDEV would otherwise maintain for you.
  • .ddev/php/*.ini applies to CLI and FPM at once. The CLI, however, may need higher limits, for example memory_limit for PHPStan or batch imports. Bake FPM-only settings into the image:
dockerfile
# .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: 30MB in Caddy is 30 × 1000², 30M in PHP and 30m in 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 in src/ or config/ only takes effect after the worker restarts (ddev exec supervisorctl restart 'webextradaemons:*'). The watch directive restarts it on change, but only give it paths to source files. The default pattern watches the whole project, including var/cache/, where Symfony writes PHP files at runtime.
yaml
# .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_ini in FRANKENPHP_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:

yaml
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:

bash
#!/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/:

bash
; .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 needs PANTHER_NO_SANDBOX=1 and PANTHER_CHROME_ARGUMENTS="--disable-dev-shm-usage" in .env.test.
  • A second project address via additional_hostnames: [test.project] and a separate server block in .ddev/nginx_full/test-env.conf that passes fastcgi_param APP_ENV test to 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 test environment 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 e2e command.

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:

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 → the DDEV_PRIMARY_URL and DDEV_PRIMARY_URL_WITHOUT_PORT environment 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_hostnames containing 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:
yaml
# .ddev/docker-compose.redis_extra.yaml
services:
  redis:
    ports:
      - "127.0.0.1:${REDIS_HOST_PORT:-6379}:6379"
bash
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_daemons and web_extra_exposed_ports, like Vite, it finds the backend of its own copy via DDEV_PRIMARY_URL and 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.local has 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 OAuth redirect_uri on localhost:3000, it is worth deriving it from DDEV_PRIMARY_URL in 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:

  1. Copy the ignored files (.env.local, auth.json, uploaded data).
  2. Transfer the database with a snapshot: ddev snapshot --name copy in the source, move the file from .ddev/db_snapshots/ and run ddev snapshot restore copy in the copy.
  3. 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) in upload_dirs, then run ddev mutagen reset.
  • Run git on the host. After switching branches, ddev mutagen sync helps, ideally from a post-checkout git hook.
  • Don't commit performance_mode. It belongs in the global configuration or config.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):
yaml
additional_fqdns:
    - project.192.168.0.10.nip.io
  • Some routers and DNS filters drop answers with a local IP (DNS rebinding protection). A hosts entry 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 share helps.

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-redis and adjustments in an _extra file.
  • A copy of nginx-site.conf for 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 psql in instructions → ddev psql, ddev import-db, ddev snapshot.
  • The database port copied into documentation → ddev describe or host_db_port.
  • Builds and downloads from external services in post-start → a custom ddev setup command.
  • DATABASE_URL or MAILER_DSN by hand in .env.local or in web_environment → leave it to DDEV, .env.test for tests.
  • A frontend on the host next to DDEV → web_extra_daemons and web_extra_exposed_ports.
  • An init SQL script for CREATE EXTENSION → a Doctrine migration.
  • A "run ddev restart after 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-config lists exactly what in .ddev/ applies and in what order.

Tags Backend, PHP

Share LinkedIn Facebook

Need more than an article?

A few sentences about what you are dealing with are enough.