On Wodby

How Varnish 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.

Overview

Technical profile and packaging

This page shows how Varnish 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

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 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

1 config can be versioned with the service.

Derived services

Build your own service on top of Varnish

These services already extend Varnish. They show how the same base runtime can be turned into more specialized building blocks without rebuilding everything from scratch.

Replacement

Vinyl is the modern replacement for Varnish

The open source Varnish project changed its name to Vinyl. If you want the current community-driven continuation, use the Vinyl service as the direct replacement.