DDEV Wildcard DNS

Overview

This add-on runs a project-local wildcard DNS resolver for your DDEV project. It maps the configured wildcard domain to the DDEV router, which allows tools running inside the web container, such as Puppeteer and Playwright, to resolve DDEV hostnames properly.

Without it, only the hostnames declared in the project configuration resolve to the router from inside the container. Any other *.ddev.site subdomain falls through to public DNS, which answers 127.0.0.1, so the request ends up at the container itself rather than at the router.

See the blog post for additional context.

If you have a fixed set of subdomains that need supporting, you can add them explicitly to your additional_hostnames saving the need to use this add-on, however a restart will be needed for them to be picked up.

Whereas having the custom DNS should allow it to work for any new domains without issue.

Installation

ddev add-on get codebymikey/ddev-wildcard-dns
ddev restart

After installation, make sure to commit the .ddev directory to version control.

The add-on starts a wildcard-dns service and automatically adds that service as a resolver in the web container during the post-start hook. No manual DNS configuration is required.

The resolver waits for the DDEV router to come up before answering, and if the router is later recreated on a different IP address, for example when another project starts, it picks up the new address automatically.

Usage

The default wildcard domain is the project’s DDEV top-level domain, normally ddev.site. For example, demo.example.ddev.site resolves to the DDEV router when the project uses ddev.site.

Registering the resolver in other services

The add-on registers the resolver automatically in the web service. To enable wildcard DNS resolution in another service, add a post-start hook for that service in a project config file, such as .ddev/config.yaml. The script writes /etc/resolv.conf, so it has to run as root or as a user with sudo; when the service’s default user is neither, run the hook as root with user::

hooks:
  post-start:
    - service: db
      exec: /mnt/ddev_config/wildcard-dns/register-resolver.sh
    # A service whose default user is unprivileged and has no sudo.
    - service: playwright-mcp
      user: root
      exec: /var/www/html/.ddev/wildcard-dns/register-resolver.sh playwright-mcp

The script accepts an optional label as its first argument, which is only used to prefix its log output. It defaults to the container hostname.

For a custom service, make sure the project’s .ddev directory is mounted at /mnt/ddev_config (or adjust the path in the hook, for example to /var/www/html/.ddev/... when the service mounts the project root instead). The service image must provide getent, awk and mktemp.

When the script cannot register the resolver (no getent, no root and no sudo, or /etc/resolv.conf not writable) it prints the reason to stderr and exits 0, so ddev start still succeeds and the service keeps its default resolver.

Restart the project after adding the hook:

ddev restart

Customization

Set options in the project’s DDEV environment file, then restart the project. The environment file is project-specific and should be committed with the rest of .ddev:

ddev dotenv set .ddev/.env.wildcard-dns \
  --ddev-wildcard-dns-debug=true
ddev restart

Supported variables:

To limit wildcard resolution to the current project, set the domain to the project’s full hostname:

ddev dotenv set .ddev/.env.wildcard-dns \
  --ddev-wildcard-dns-domain=my-project.ddev.site
ddev restart

Replace my-project with your DDEV project name.

When debug mode is enabled, dnsmasq logs DNS queries and debug messages. View them with:

ddev logs -s wildcard-dns

Credits

Contributed and maintained by @codebymikey