Service type
Vinyl service
Vinyl HTTP cache service for accelerating web responses.
Use it as a reusable, versioned service inside custom or predefined stacks so teams can keep the runtime and operational model consistent.
Why teams use this service
On Wodby
How Vinyl runs on Wodby
Where it sits
- It listens on port
6081, the service's main HTTP endpoint, and forwards to one backend. - The
backendlink is required and points at a web server service (Nginx or Apache). It setsVARNISH_BACKEND_HOSTandVARNISH_BACKEND_PORT, which the image writes into the backend definition. Do not define the backend in VCL. - All variables keep the
VARNISH_andVARNISHD_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
mainconfig 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_PRESETselects an application preset (drupalorwordpress). This service sets none; the Drupal and WordPress variants of the service do.
Default caching rules
- Only
GETandHEADare cached. AJAX requests (X-Requested-With: XMLHttpRequest) are not. - A backend response with
Set-Cookie,Cache-Control: private,Cache-Control: no-cacheorX-VC-Cacheable: NOis not cached. - Static files are passed to the backend uncached unless
VARNISH_CACHE_STATIC_FILESis set. - Responses larger than
VARNISH_BIG_FILES_SIZEare not cached. - Tracking query parameters and cookies are stripped (
VARNISH_STRIP_PARAMS,VARNISH_STRIP_COOKIES) unlessVARNISH_KEEP_ALL_PARAMSorVARNISH_KEEP_ALL_COOKIESis set. Cookies namedVCKEY-<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 default64M). It is empty after every restart, and each replica has its own cache. - Default lifetime:
VARNISH_DEFAULT_TTLandVARNISHD_DEFAULT_TTL.
Purging
PURGEandBANrequests sent to port6081invalidate by URL and host. HeaderX-VC-Purge-Methodchoosesregexorexact; the default ignores the query string. ABANrequest with aCache-Tagsheader also invalidates every object whoseCache-Tagsmatches.- Wodby generates a purge key (
VARNISH_PURGE_KEY), sent by clients in theX-VC-Purge-Keyheader. - The manifest sets
VARNISH_PURGE_EXTERNAL_REQUEST_HEADERtoX-Real-IP: a request that carries anX-Real-IPheader must present the key, or it gets405. 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-CacheisHITorMISS. - The reason for a decision is in
X-VC-Cacheable, which is delivered only when the backend response carries the headerX-VC-Debug: true(the same header sent by a client is removed). GET /.vchealthzanswers204from the cache itself, without the backend.- From this service's container:
make check-ready -f /usr/local/bin/actions.mk, andmake flush -f /usr/local/bin/actions.mkbans everything.
Overview
Technical profile and packaging
Versions
Source repository
Public Helm chart
Ports and protocols
Labels
Stacks
Use it inside ready-made stacks or your own
Runtime wiring
Reuse connectivity, storage, and runtime defaults
Endpoints
Technical domains
Configs
Service links
These links define which other services can connect to Vinyl when it is used inside a stack.
Derived services