DDEV Varnish

Overview

Varnish Cache is a web application accelerator also known as a caching HTTP reverse proxy. You install it in front of any server that speaks HTTP and configure it to cache the contents. Varnish Cache is really, really fast. It typically speeds up delivery with a factor of 300 - 1000x, depending on your architecture.

This add-on integrates Varnish into your DDEV project.

Installation

ddev add-on get ddev/ddev-varnish
ddev restart

Note

Run ddev add-on get ddev/ddev-varnish after changes in name, additional_hostnames, additional_fqdns, project_tld, the Mailpit ports, or web_extra_exposed_ports in .ddev/config.yaml so that .ddev/docker-compose.varnish_extras.yaml is regenerated.

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

Usage

The Varnish service inserts itself between ddev-router and the web container for port 80/443 only. Mailpit and web_extra_exposed_ports continue to route directly to the web container, bypassing Varnish.

A docker-compose.varnish_extras.yaml file is generated on install which:

• Removes port 80 from the web container's HTTP_EXPOSE and HTTPS_EXPOSE so Varnish owns that traffic.
• Extends the Varnish container's VIRTUAL_HOST to also accept novarnish.* subdomains (e.g. novarnish.mysite.ddev.site). Requests to these subdomains are piped directly to the backend by VCL, bypassing the cache without adding Varnish headers — useful for comparing cached vs. uncached responses.

Note

If you use a project_tld other than ddev.site or additional_fqdns, DDEV adds /etc/hosts entries for your project hostnames automatically, but not for novarnish.* subdomains. Add them manually: ddev hostname novarnish.mysite.example.com 127.0.0.1.

Helper Commands

This add-on also providers several helper commands. These helpers allow developers to run Varnish commands from the host, however, the commands are actually run inside the Varnish container.

Command	Description
ddev varnishd	Varnish-cli
ddev varnishadm	Control a running Varnish instance
ddev varnishhist	Display Varnish request histogram
ddev varnishlog	Display Varnish logs
ddev varnishncsa	Display Varnish logs in Apache / NCSA combined log format
ddev varnishstat	Display Varnish Cache statistics
ddev varnishtest	Test program for Varnish
ddev varnishtop	Display Varnish log entry ranking
ddev varnish-config-reload	Reloads the varnish current config to apply changes
ddev describe	View service status and used ports for Varnish
ddev ssh -s varnish	Go into the Varnish container shell
ddev logs -s varnish	Check Varnish logs

See The Varnish Reference Manual for more information about the commands, their flags, and their arguments.

Advanced Customization

You may want to edit the .ddev/varnish/default.vcl to meet your needs. The default VCL pipes novarnish.* requests directly to the backend (no caching, no Varnish headers). Remember to remove #ddev-generated from the file if you want your changes preserved.

To change the Docker image:

ddev dotenv set .ddev/.env.varnish --varnish-docker-image=varnish:6.0
ddev add-on get ddev/ddev-varnish
ddev restart

Make sure to commit the .ddev/.env.varnish file to version control.

All customization options (use with caution):

Variable	Flag	Default
VARNISH_DOCKER_IMAGE	--varnish-docker-image	varnish:6.0
VARNISH_VARNISHD_PARAMS	--varnish-varnishd-params	-p http_max_hdr=1000 -p http_resp_hdr_len=1M -p http_resp_size=2M -p workspace_backend=3M -p workspace_client=3M

VARNISH_VARNISHD_PARAMS

Allows modifying the varnish startup parameters.

The provided defaults are set deliberately higher than what varnish usually defines. The reason for this is that in development environments it is not uncommon to have larger payloads either in HTML or HTTP-Headers. E.g. Drupals theme debugging or cache tag handling. Without increasing these limits, one might encounter hard to isolate errors like the following form nginx:

2025/07/15 09:01:01 [info] 1549#1549: *259 writev() failed (32: Broken pipe) while sending to client, client: 172.20.0.6, server: , request: "GET /en HTTP/1.1", upstream: "fastcgi://unix:/run/php-fpm.sock:", host: "myproject.ddev.site"

Credits

Maintained by @jedubois and the DDEV team

Based on the original ddev-contrib recipe pioneered by rikwillems