ddev-expert
DDEV local development expertise. Use when working with DDEV projects, containers, configuration, or troubleshooting DDEV environments.
How do I install this agent skill?
npx skills add https://github.com/edutrul/drupal-ai --skill ddev-expertIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The ddev-expert skill provides specialized instructions for managing DDEV local development environments. It includes troubleshooting commands that require administrative privileges (sudo) to resolve port conflicts and system-level process termination (killall) to recover from Docker Desktop errors. It also references official DDEV Docker images and GitHub Actions for CI/CD integration.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
DDEV Expert
Essential Commands
# Project
ddev start | stop | restart | poweroff | delete
# Execute
ddev drush <cmd> | ddev composer <cmd> | ddev exec <cmd> | ddev ssh
# Database
ddev mysql | ddev export-db | ddev import-db --file=dump.sql
ddev snapshot | ddev restore
# Utilities
ddev describe # URLs and project info
ddev logs -f # Follow logs
ddev launch # Open in browser
ddev launch -m # Open Mailpit UI
Configuration (.ddev/config.yaml)
name: my-project
type: drupal # auto-detects version; or drupal11/drupal10
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
database:
type: mariadb
version: "10.11"
additional_hostnames:
- api.my-project.ddev.site
webimage_extra_packages: [php8.3-imagick]
mutagen_enabled: true # macOS/Windows performance
Overrides: .ddev/config.local.yaml (gitignored personal config)
PHP overrides: .ddev/php/*.ini
Troubleshooting
ddev composer create-project fails ("not allowed to be present"):
Move extra dirs out temporarily (.claude/, .git/), run create-project, move back.
Port conflicts:
ddev poweroff && sudo lsof -i :80
Container issues:
ddev restart
ddev debug refresh # Rebuild containers
ddev delete && ddev start # Nuclear option
Database: Host is db (inside container) or 127.0.0.1:PORT (outside). Check port with ddev describe.
Permissions: ddev exec chown -R $(id -u):$(id -g) .
PHP deprecation warnings in Drush — create .ddev/php/drush.ini:
[PHP]
error_reporting = 22527 ; E_ALL & ~E_DEPRECATED
display_errors = Off
log_errors = On
error_log = /tmp/php-errors.log
Docker Desktop overlay2 I/O errors — normal restart is not enough:
killall -9 Docker # then relaunch Docker Desktop
Mutagen sync hanging after Docker crash:
ddev poweroff && ddev start
# If still stuck:
ddev stop
~/.ddev/bin/mutagen daemon stop
~/.ddev/bin/mutagen daemon start
ddev mutagen reset && ddev start
ddev mutagen status -l # Detailed sync status
ddev mutagen monitor # Real-time progress
Debug commands:
ddev debug capabilities | ddev debug router
ddev exec env
Xdebug
ddev xdebug on | off | status
.ddev/php/xdebug.ini:
[xdebug]
xdebug.mode=debug,develop,coverage
Modes: debug (step), develop (enhanced errors), coverage, profile.
See README.md for full IDE setup (VS Code / PHPStorm).
Custom Services
Add .ddev/docker-compose.<service>.yaml. Common pattern:
services:
redis:
image: redis:7-alpine
container_name: ddev-${DDEV_SITENAME}-redis
labels:
com.ddev.site-name: ${DDEV_SITENAME}
com.ddev.approot: $DDEV_APPROOT
expose:
- "6379"
See README.md for full Solr, Elasticsearch, Redis configs and Drupal settings.php snippets.
Custom Commands
Create .ddev/commands/web/<name> (or host/, db/):
#!/bin/bash
## Description: Full site refresh
## Usage: refresh
set -e
drush sql:drop -y && drush sql:cli < /var/www/html/reference.sql
drush config:import -y && drush updatedb -y && drush cache:rebuild
chmod +x then run as ddev <name>.
Performance (macOS/Windows)
ddev config global --mutagen-enabled # Enable globally
ddev mutagen status | sync | reset
See README.md for NFS, tmpfs, and file sync exclusion patterns.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/edutrul/drupal-ai/ddev-expert">View ddev-expert on skillZs</a>