ddev-ops

Files (40)

• SKILL.md
• ddev-facts.json · assets/
• sanitized-pull.yaml.example · assets/
• automation-and-worktrees.md · references/
• config-and-env.md · references/
• database.md · references/
• debugging-sharing.md · references/
• extending.md · references/
• frontend-node.md · references/
• performance.md · references/
• troubleshooting.md · references/
• audit-ddev-config.py · scripts/
• check-ddev-facts.py · scripts/
• run-python.sh · scripts/
• addon-dashboard · tests/fixtures/clean/.ddev/commands/host/
• db-sanitize · tests/fixtures/clean/.ddev/commands/web/
• config.local.yaml · tests/fixtures/clean/.ddev/
• config.yaml · tests/fixtures/clean/.ddev/
• docker-compose.cache.yaml · tests/fixtures/clean/.ddev/
• api-proxy.conf · tests/fixtures/clean/.ddev/nginx/
• staging.yaml · tests/fixtures/clean/.ddev/providers/
• .gitkeep · tests/fixtures/clean/storage/
• .gitkeep · tests/fixtures/clean/web/
• commands-db.json · tests/fixtures/live/
• commands-host.json · tests/fixtures/live/
• commands-web.json · tests/fixtures/live/
• config.md · tests/fixtures/live/
• eol-nodejs.json · tests/fixtures/live/
• eol-php.json · tests/fixtures/live/
• releases.json · tests/fixtures/live/
• schema.json · tests/fixtures/live/
• open-admin · tests/fixtures/minefield/.ddev/commands/host/
• craft · tests/fixtures/minefield/.ddev/commands/web/
• config.yaml · tests/fixtures/minefield/.ddev/
• docker-compose.agent.yaml · tests/fixtures/minefield/.ddev/
• docker-compose.tools.yaml · tests/fixtures/minefield/.ddev/
• production.yaml · tests/fixtures/minefield/.ddev/providers/
• .gitkeep · tests/fixtures/minefield/storage/
• .gitkeep · tests/fixtures/minefield/web/
• run.sh · tests/

SKILL.md (first lines)

# 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`.
2. **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.
3. **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.
4. **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.
5. **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"`.
2. **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`.
3. **Retired keys do nothing.** DDEV loads config non-strictly:
   `mutagen_enabled: false` and `nfs_mount_enabled` are ignored, not obeyed.
4. **`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.
5. **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`.
6. **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`.
7. **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.
8. **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.
9. **Review an add-on before installing it.** Its Bash install actions run on your
   machine. Prefer official `ddev/` add-ons and pin `--version`.
10. **On Windows, keep projects inside the WSL2 filesystem**, never under `/mnt/c`.
11. **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.
12. **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](references/database.md#keep-dumps-out-of-an-agents-context)).
- **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](references/automation-and-worktrees.md).

## Route by task

| Task | Read |
|---|---|
| Existing repo on a new machine, new project, version pinning, CI parity, Composer, what to commit, env files, upgrading DDEV | [config-and-env.md](references/config-and-env.md) |
| Scripting DDEV, JSON output, commands that destroy data, several git worktrees (OAuth callbacks, webhooks), renaming or moving a project, AI agents inside DDEV | [automation-and-worktrees.md](references/automation-and-worktrees.md) |
| Import/export, snapshots, seed and reset, changing engine, `ddev pull` recipes, sanitised data, uploads from production, dumps and agents | [database.md](references/database.md) |
| Slow project, Mutagen, `upload_dirs`, WSL2, choosing a Docker provider | [performance.md](references/performance.md) |

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods