App service
Services/Varnish (Drupal)

Varnish (Drupal) service

Legacy Varnish HTTP cache service with Drupal presets for caching responses in front of a Drupal application.

Use it as a reusable, versioned service inside custom or predefined stacks so teams can keep the runtime and operational model consistent.

On Wodby

How Varnish (Drupal) runs on Wodby

What Wodby sets up for this Varnish HTTP cache (it runs the same wodby/vinyl image as the Vinyl service). Check it before writing VCL or adding cache purging to an application.

Where it sits

  • It listens on port 6081, the service's main HTTP endpoint, and forwards to one backend.
  • The backend link is required and points at a web server service (Nginx or Apache). It sets VARNISH_BACKEND_HOST and VARNISH_BACKEND_PORT, which the image writes into the backend definition. Do not define the backend in VCL.
  • All variables keep the VARNISH_ and VARNISHD_ prefixes.

Generated configuration

On every start the container renders the VCL into /etc/varnish from templates in /etc/gotpl and from environment variables: default.vcl, preset.vcl, defaults/*.vcl and includes/*.vcl. The rendered files are rewritten on each start: never edit them.

  • Behavior is changed with environment variables on this service.
  • The main config of the manifest is the template /etc/gotpl/default.vcl.tmpl. Override it there when custom VCL is needed; it is a template, so it still goes through variable substitution.
  • VARNISH_CONFIG_PRESET selects an application preset (drupal or wordpress). This service sets none; the Drupal and WordPress variants of the service do.

Default caching rules

  • Only GET and HEAD are cached. AJAX requests (X-Requested-With: XMLHttpRequest) are not.
  • A backend response with Set-Cookie, Cache-Control: private, Cache-Control: no-cache or X-VC-Cacheable: NO is not cached.
  • Static files are passed to the backend uncached unless VARNISH_CACHE_STATIC_FILES is set.
  • Responses larger than VARNISH_BIG_FILES_SIZE are not cached.
  • Tracking query parameters and cookies are stripped (VARNISH_STRIP_PARAMS, VARNISH_STRIP_COOKIES) unless VARNISH_KEEP_ALL_PARAMS or VARNISH_KEEP_ALL_COOKIES is set. Cookies named VCKEY-<name> are kept and become part of the cache key.
  • The cache key includes the host and the request protocol.
  • The cache is in memory only, sized by VARNISHD_MEMORY_SIZE (image default 64M). It is empty after every restart, and each replica has its own cache.
  • Default lifetime: VARNISH_DEFAULT_TTL and VARNISHD_DEFAULT_TTL.

Purging

  • PURGE and BAN requests sent to port 6081 invalidate by URL and host. Header X-VC-Purge-Method chooses regex or exact; the default ignores the query string. A BAN request with a Cache-Tags header also invalidates every object whose Cache-Tags matches.
  • Wodby generates a purge key (VARNISH_PURGE_KEY), sent by clients in the X-VC-Purge-Key header.
  • The manifest sets VARNISH_PURGE_EXTERNAL_REQUEST_HEADER to X-Real-IP: a request that carries an X-Real-IP header must present the key, or it gets 405. A request without that header, such as one sent by an application straight to this service inside the environment, is accepted without the key.
  • With several replicas a purge reaches only the replica that received the request.

Management secret

VARNISH_SECRET is generated by Wodby and written to /etc/varnish/secret. It authenticates the management interface on port 6082, which is not a declared endpoint. Applications do not need it.

Check the result

  • Response header X-VC-Cache is HIT or MISS.
  • The reason for a decision is in X-VC-Cacheable, which is delivered only when the backend response carries the header X-VC-Debug: true (the same header sent by a client is removed).
  • GET /.vchealthz answers 204 from the cache itself, without the backend.
  • From this service's container: make check-ready -f /usr/local/bin/actions.mk, and make flush -f /usr/local/bin/actions.mk bans everything.

Varnish for Drupal on Wodby

What this service adds to the Varnish service it is based on.

Drupal preset

VARNISH_CONFIG_PRESET is set to drupal, so the image renders its Drupal rules into /etc/varnish/preset.vcl:

  • Requests matching VARNISH_DRUPAL_EXCLUDE_URLS go to the backend uncached. The default covers /update.php, /admin, /system/files/, /flag/ and AJAX paths, with an optional two-letter language prefix. Batch pages are piped.
  • Only cookies matching VARNISH_DRUPAL_PRESERVED_COOKIES are kept (by default Drupal session cookies and NO_CACHE); all others are removed before the cache lookup. A request that still has a cookie is not cached, so pages of signed-in users always come from Drupal. VARNISH_KEEP_ALL_COOKIES does not change this.

The preset template is the drupal config of the manifest (/etc/gotpl/presets/drupal.vcl.tmpl). Override it there, not in the rendered file.

Cache tags

  • VARNISHD_PARAM_HTTP_RESP_HDR_LEN is raised so that Drupal's long cache-tag headers fit.
  • A BAN request with a Cache-Tags header invalidates every cached object whose Cache-Tags response header matches it. For tag-based invalidation Drupal must send its tags in a Cache-Tags response header and send its invalidations as BAN requests to this service on port 6081. That is done with Drupal's purge modules and configuration; this service does not configure Drupal.

Check the result

  • An anonymous page requested twice returns X-VC-Cache: HIT the second time. A MISS every time usually means the response sets a cookie or sends Cache-Control: private or no-cache: Drupal's page cache maximum age must be above zero.
  • The reason is in X-VC-Cacheable, delivered only when the backend response carries the header X-VC-Debug: true.

Overview

Technical profile and packaging

This page shows how Varnish (Drupal) is packaged and versioned as a Wodby service, what it exposes at runtime, and which source artifacts it builds on.

Service type

App service

Versions

9.1, 8.0, 6.0

Ports and protocols

6081/HTTP

Labels

drupal, varnish, varnish

Stacks

Use it inside ready-made stacks or your own

This service is available as a reusable building block even when it is not currently exposed by one of the public stacks.
Build a custom stack around Varnish (Drupal) when you want this service without the constraints of a predefined stack.

Runtime wiring

Reuse connectivity, storage, and runtime defaults

This service can expose ports, connect to other services, attach persistent storage, and define runtime defaults that become reusable inside stacks rather than being rebuilt case by case.

Endpoints

6081/HTTP

Technical domains

HTTP endpoints from this service can use technical domains with auto-renewed TLS certificates on Wodby.

Configs

2 configs can be versioned with the service.