0xdarkmatter/claude-mods/ddev-ops

DDEV Operations

Why: DDEV is the local stack behind most PHP agency sites, and it fails quietly: a default that moved under an unpinned project, a key it silently ignores, one developer's setting committed for the whole team.

Versions verified 2026-10-05 against DDEV v1.25.4. Fast-moving facts (defaults, PHP and

Node.js end-of-life floors, built-in command names) live once in

assets/ddev-facts.json; scripts/check-ddev-facts.py --offline fails if this skill's

prose and that file disagree, and --live (weekly) fails when DDEV moves.

Start here

1. Read the project before changing it: .ddev/config.yaml, any config.*.yaml,

ls -a .ddev/, then ddev describe (URLs, ports, services) and ddev version.

1. Audit it from any directory, <skill-dir> being this skill's folder (the launcher

finds a working Python 3.8+, which matters on Windows where python3 is often a Store stub):

``bash bash "<skill-dir>/scripts/run-python.sh" "<skill-dir>/scripts/audit-ddev-config.py" /path/to/project bash "<skill-dir>/scripts/run-python.sh" "<skill-dir>/scripts/audit-ddev-config.py" /path/to/project --json | jq '.data[]' ``

Exit 10 means findings, sorted high to low (severity, check, file:line, detail); 0 means clean. --ignore <check> documents a deliberate exception.

1. Run everything through DDEV - ddev composer, ddev php, ddev npm,

ddev exec - so commands use the container's PHP and Node, not the host's.

1. Snapshot before anything risky, with a unique name:

ddev snapshot --name=before-<task>-$(date +%Y%m%d%H%M%S). A reused name saves nothing and still exits 0.

1. Ask before destroying data (Hard rule 11).

Hard rules

Rules 2, 3, 4, 6, 8 and 12 were each seen in a 2026-10-05 read of 36 DDEV-based agency repositories; the rest are quiet failures DDEV's own docs and source describe.

1. Pin `php_version` and `database` to production. Unpinned projects follow DDEV's

defaults, which move: v1.25.0 switched PHP 8.3 to 8.4 and MariaDB 10.11 to 11.8. Also pin nodejs_version and composer_version: "2".

1. Per-developer settings never go in `config.yaml`.

• That means performance_mode, router_http_port/router_https_port,

xdebug_enabled: true, bind_all_interfaces and host_db_port.

• They belong in .ddev/config.local.yaml or ddev config global.
• Project values beat global ones, so a committed value pins every teammate.
• Git ignores the .local files only after DDEV has run in that checkout, because

its .ddev/.gitignore isn't committed. Add .ddev/config*.local.y*ml and .ddev/.env*.local to the project root's .gitignore.

1. Retired keys do nothing. DDEV loads config non-strictly:

mutagen_enabled: false and nfs_mount_enabled are ignored, not obeyed.

1. `upload_dirs` resolve from the docroot. With docroot: web, storage means

web/storage; folders beside the docroot are ../storage and ../node_modules. Setting the list replaces the type's defaults; override files append to it.

1. No secrets in committed `.ddev/.env*` files. Use the .local twin

(.ddev/.env.web.local, v1.25.4+), kept out of git as rule 2 says. Commit a .example with git add -f, since DDEV's .gitignore hides *.example.

1. Never hand containers your machine's credentials. Every process in them -

Composer and npm scripts included - can use what they reach.

• No host SSH-agent forwarding: load one scoped key with ddev auth ssh -f <key>.
• No compose mount of the Docker socket (full control of the host) or of your home

directory.

• No agent logins or keys under .ddev/: the project, .ddev/ included, is mounted

into web.

1. Pull sanitised data; never push to production.

• Anonymise where the data lives and pull the result. No raw production personal data

on laptops.

• Delete db_push_command/files_push_command from your own recipes that can reach

production.

• A files_pull_command that fetches nothing makes ddev pull empty the upload

directory, and the pull still exits 0. Omit the stanza instead.

1. Don't keep project copies of DDEV's built-in commands (craft, npm,

artisan, wp...). A project command shadows the built-in and freezes an old version. Command files must have LF endings: DDEV skips CRLF ones with only a warning.

1. Review an add-on before installing it. Its Bash install actions run on your

machine. Prefer official ddev/ add-ons and pin --version.

1. On Windows, keep projects inside the WSL2 filesystem, never under /mnt/c.
2. Confirm with the user before destroying data. These destroy data:

• ddev delete, ddev stop --remove-data, ddev start --reset-database;
• ddev snapshot --cleanup, ddev clean, ddev push;
• ddev import-db and ddev import-files, which empty their target first;
• docker volume prune -a, which deletes stopped projects' databases.

ddev poweroff stops everyone's projects.

1. Several checkouts need distinct project names. A committed name: makes every git

worktree claim the same project. Omit it, or override it in config.local.yaml.

Driving DDEV from a script or agent

• `ddev` is not a sandbox. Project host commands and exec-host hook tasks run on

your machine with your rights; a pre-start one runs on the first ddev start. In a repository you didn't write, audit first and show the user any host-hook or host-command finding before starting the project.

• Never run bare `ddev` (it opens a dashboard) or flagless `ddev config` (it asks

questions). Pass --file/--source to imports and -y to anything that prompts.

• Name the container directory. ddev exec ignores the host folder you run it from;

pass --dir /var/www/html/<path>, or a plugin's suite runs against the project's config and development database.

• Keep dumps out of your context: ask the database (ddev mysql -e '...'), never

read a dump or snapshot (database.md).

• Read state as JSON: ddev describe -j | jq -r '.raw.primary_url' (also

.raw.status, .raw.dbinfo.published_port); ddev list -j; ddev launch --print-url.

• Single-quote `ddev exec` commands that contain $, pipes or redirects, so they

expand inside the container.

• Exit 0 isn't always success: a duplicate ddev snapshot name and

ddev add-on remove leaving files behind both exit 0.

Details, the destroys-data table and worktree setup: automation-and-worktrees.md.

Route by task

Everyday commands

Scripts and assets

The auditor:

• Checks:
• versions: php-unpinned, php-out-of-range, php-eol, db-unpinned, node-eol,

composer-v1;

• config: obsolete-key, unknown-key (against DDEV's own config schema),

perf-mode-committed, router-ports-committed, xdebug-committed, name-in-worktree;

• folders and commands: upload-dir-misplaced, upload-dir-outside,

shadowed-command, crlf-command;

• the host: host-command, host-hook, ssh-agent-forwarded,

docker-socket-mounted, home-mounted;

• safety: provider-push, provider-files-noop, committed-secret (env, config,

compose and web-server files), credential-file, local-file-committed (reads git's index; never runs a git or fsmonitor command the audited repository supplies).

• Exit codes: 0 clean, 10 findings, 3 no .ddev/config.yaml, 4 unreadable config,

2 usage.

• It reads config the way DDEV does: overrides merge, lists append. It skips DDEV's

own generated recipes and never prints a secret value.

Boundaries