DDEV, Varnish, and Xdebug for Magento GraphQL development

2023-07-02 · Ben Williamson

Why I finally wrote this down

I was working through a GraphQL certification final exam that assumed Warden or Den for local Magento. I have used Warden; for day-to-day Community Edition work I still prefer DDEV. The course notes scattered across several Evernote pages covered Colima, down-sync scripts, and mutagen on Mac, but not the full-page cache layer that makes GraphQL behave differently in staging.

This post compiles the local setup I actually use: DDEV for Magento CE, the ddev-varnish add-on when I need realistic FPC headers, and Xdebug toggled for resolver step-through. The goal is parity with cloud, not the smallest possible docker-compose.

What "trimmed" local means

Match cloud, add only what the feature needs:

  • DDEV project with PHP version aligned to target cloud.

  • Varnish container via ddev-varnish when testing cache-sensitive storefront paths.

  • Xdebug enabled only while stepping through resolvers and plugins (ddev xdebug on, then off when done).

  • Database source: sample data for greenfield work, or a down-synced DB when debugging catalog scope issues.

On Linux I run Colima or native Docker; on Mac, Mutagen sync is worth the setup cost. The exam environment does not need every enterprise module, but it does need the same search and cache dependencies as staging or you debug the wrong layer.

Standing up Varnish in DDEV

The ddev-varnish project documents an add-on install. After enabling it, treat VCL and backend routing as part of the repo notes, not tribal knowledge. I forked the add-on once to match our hostname pattern; link your fork in the README if you do the same.

Typical flow:

ddev get ddev/ddev-varnish
ddev restart
# confirm Varnish fronts the web container; hit a known cacheable route

If Magento install commands behave oddly through the wrapper, SSH into the web container for setup:install and early bin/magento commands. I have seen less friction that way on fresh projects.

GraphQL-specific tips

Validate resolvers before caching muddies the signal:

  • Test with full-page cache disabled first. Confirm resolver output and plugins.

  • Re-enable Varnish and repeat. Cache headers and edge behavior should match staging.

  • Keep a known-good introspection query in the repo for quick schema diffs between branches.

  • Align graphql.php complexity and depth limits with cloud when debugging "query too complex" errors.

Parity with staging is the point

If local cannot run the same modules and search dependencies as staging, you will fix problems in Vue or GraphQL that are actually missing indexers or wrong store view scope. The certification exercise is a good forcing function: same stack shape, smaller dataset.

Shortcut for teammates willing to clone a prepared repo: document which step to start at (clone + ddev start) versus from-scratch (composer create-project + install). Both paths should land on the same Varnish and Xdebug toggles.

Quick review before you trust local

  • Does PHP version match target cloud?

  • Did I reproduce the bug with Varnish on?

  • Is Xdebug off during performance testing?

  • Does a scoped GraphQL query behave the same against staging and local DB snapshots?