Vinyl Cache (Varnish Cache) Docker Container Image

• Docker images
• Environment variables
• Installed modules
• Default behaviour
  • Caching rules
  • Cache personification
  • GeoIP
  • Currency
  • Flushing
  • Miscellaneous
• Config presets
  • Drupal
  • WordPress
• PageSpeed downstream caching
• Orchestration actions
• Deployment

Docker Images

❗For better reliability we release images with stability tags (wodby/vinyl:8-X.X.X) which correspond to git tags. We strongly recommend using images only with stability tags.

Overview:

• All images are based on Alpine Linux
• Base image: wodby/alpine
• GitHub actions builds
• Docker Hub
• Helm chart

All images built for linux/amd64 and linux/arm64

Supported tags and respective Dockerfile links:

• 8.0, 8, latest (Dockerfile)
• 6.0, 6 (Dockerfile)

Environment Variables

Variable	Default Value	Description
VARNISH_ALLOW_UNRESTRICTED_PURGE		Used for ban requests as well
VARNISH_BACKEND_BETWEEN_BYTES_TIMEOUT	60s
VARNISH_BACKEND_CONNECT_TIMEOUT	3.5s
VARNISH_BACKEND_FIRST_BYTE_TIMEOUT	60s
VARNISH_BACKEND_GRACE	2m
VARNISH_BACKEND_HOST		Mandatory
VARNISH_BACKEND_PORT	80
VARNISH_CACHE_PER_COUNTRY		Separate caches based on country code
VARNISH_CACHE_PER_CURRENCY		Separate caches based on currency
VARNISH_CURRENCY_EUR_COUNTRY_CODES		See currencies
VARNISH_CURRENCY_USD_COUNTRY_CODES		See currencies
VARNISH_BIG_FILES_SIZE	10485760	10MB
VARNISH_BIG_FILES_TTL	120s
VARNISH_CACHE_STATIC_FILES
VARNISH_CONFIG_PRESET
VARNISH_DEFAULT_TTL	120s
VARNISH_ERRORS_GRACE	15s
VARNISH_PURGE_EXTERNAL_REQUEST_HEADER
VARNISH_KEEP_ALL_COOKIES
VARNISH_KEEP_ALL_PARAMS
VARNISH_IMPORT_MODULES		Separated by comma
VARNISH_MOBILE_DISABLE_CASH
VARNISH_MOBILE_SEPARATE_CASH
VARNISH_MOBILE_USER_AGENT		See default value below
VARNISH_PIPE_CLOSE_CONNECTION
VARNISH_PURGE_KEY		Randomly generated if missing
VARNISH_SECONDARY_STORAGE_CONDITION		Must be valid VCL
VARNISH_SECRET		Generated automatically if missing
VARNISH_STATIC_FILES		See default value below
VARNISH_STATIC_TTL	86400	In seconds
VARNISH_STRIP_COOKIES		See default value below
VARNISH_STRIP_PARAMS		See default value below
VARNISH_STRIP_ALL_PARAMS		Ignored if $VARNISH_KEEP_ALL_PARAMS is set
VARNISH_PAGESPEED_SECRET_KEY		Should be used if mod_pagespeed is enabled
VARNISHD_DEFAULT_TTL	120
VARNISHD_MEMORY_SIZE	64m
VARNISHD_PARAM_BAN_LURKER_AGE	60.000
VARNISHD_PARAM_BAN_LURKER_BATCH	1000
VARNISHD_PARAM_BAN_LURKER_SLEEP	0.010
VARNISHD_PARAM_BETWEEN_BYTES_TIMEOUT	60.000
VARNISHD_PARAM_CONNECT_TIMEOUT	3.500
VARNISHD_PARAM_DEFAULT_GRACE	10.000
VARNISHD_PARAM_DEFAULT_KEEP	0.000
VARNISHD_PARAM_DEFAULT_TTL	120.000
VARNISHD_PARAM_FETCH_CHUNKSIZE	16k
VARNISHD_PARAM_FIRST_BYTE_TIMEOUT	60.000
VARNISHD_PARAM_GZIP_BUFFER	32k
VARNISHD_PARAM_GZIP_LEVEL	6
VARNISHD_PARAM_GZIP_MEMLEVEL	8
VARNISHD_PARAM_HTTP_GZIP_SUPPORT	on
VARNISHD_PARAM_HTTP_MAX_HDR	64
VARNISHD_PARAM_HTTP_REQ_HDR_LEN	8k
VARNISHD_PARAM_HTTP_REQ_SIZE	32k
VARNISHD_PARAM_HTTP_RESP_HDR_LEN	8k
VARNISHD_PARAM_HTTP_RESP_SIZE	32k
VARNISHD_PARAM_IDLE_SEND_TIMEOUT	60.000
VARNISHD_PARAM_MAX_ESI_DEPTH	5
VARNISHD_PARAM_MAX_RESTARTS	4
VARNISHD_PARAM_MAX_RETRIES	4
VARNISHD_PARAM_NUKE_LIMIT	50
VARNISHD_PARAM_PING_INTERVAL	3
VARNISHD_PARAM_PIPE_TIMEOUT	60.000
VARNISHD_PARAM_POOL_REQ	10,100,10
VARNISHD_PARAM_POOL_SESS	10,100,10
VARNISHD_PARAM_PREFER_IPV6	off
VARNISHD_PARAM_RUSH_EXPONENT	3
VARNISHD_PARAM_SEND_TIMEOUT	600
VARNISHD_PARAM_SHORTLIVED	10.000
VARNISHD_PARAM_TCP_KEEPALIVE_INTVL	75.000
VARNISHD_PARAM_TCP_KEEPALIVE_PROBES	8
VARNISHD_PARAM_TCP_KEEPALIVE_TIME	7200.000
VARNISHD_PARAM_THREAD_POOL_ADD_DELAY	0.000
VARNISHD_PARAM_THREAD_POOL_DESTROY_DELAY	1.000
VARNISHD_PARAM_THREAD_POOL_FAIL_DELAY	0.200
VARNISHD_PARAM_THREAD_POOL_MAX	5000
VARNISHD_PARAM_THREAD_POOL_MIN	100
VARNISHD_PARAM_THREAD_POOL_STACK	48k
VARNISHD_PARAM_THREAD_POOL_TIMEOUT	300.000
VARNISHD_PARAM_THREAD_POOLS	2
VARNISHD_PARAM_THREAD_QUEUE_LIMIT	20
VARNISHD_PARAM_TIMEOUT_IDLE	5.000
VARNISHD_PARAM_TIMEOUT_LINGER	0.050
VARNISHD_PARAM_VSL_BUFFER	4k
VARNISHD_PARAM_VSL_RECLEN	255b
VARNISHD_PARAM_VSL_SPACE	80M
VARNISHD_PARAM_VSM_SPACE	1M
VARNISHD_PARAM_WORKSPACE_BACKEND	64k
VARNISHD_PARAM_WORKSPACE_CLIENT	64k
VARNISHD_PARAM_WORKSPACE_SESSION	0.50k
VARNISHD_PARAM_WORKSPACE_THREAD	2k
VARNISHD_SECONDARY_STORAGE		See example below
VARNISHD_SECRET_FILE	/etc/varnish/secret
VARNISHD_VCL_SCRIPT	/etc/varnish/default.vcl

VARNISH_MOBILE_USER_AGENT:

Backslashes must be escaped as \\

ipod|android|blackberry|phone|mobile|kindle|silk|fennec|tablet|webos|palm|windows ce|nokia|philips|samsung|sanyo|sony|panasonic|ericsson|alcatel|series60|series40|opera mini|opera mobi|au-mic|audiovox|avantgo|blazer|danger|docomo|epoc|ericy|i-mode|ipaq|midp-|mot-|netfront|nitro|pocket|portalmmm|rover|sie-|symbian|cldc-|j2me|up\\.browser|up\\.link|vodafone|wap1\\.|wap2\\.

VARNISH_STATIC_FILES:

asc|doc|xls|ppt|csv|svg|jpg|jpeg|gif|png|ico|css|zip|tgz|gz|rar|bz2|pdf|txt|tar|wav|bmp|rtf|js|flv|swf|html|htm|webp

VARNISH_STRIP_COOKIES

Ignored if $VARNISH_KEEP_ALL_COOKIES is set

__[a-z]+|wooTracker|VCKEY-[a-zA-Z0-9-_]+

VARNISH_STRIP_PARAMS

Ignored if $VARNISH_KEEP_ALL_PARAMS is set

utm_[a-z]+|gclid|cx|ie|cof|siteurl|fbclid

VARNISH_SECONDARY_STORAGE_CONDITION:

Allows defining custom conditions for storing the cache object in the secondary storage; as it is injected into an if it has to contain valid VCL syntax for it.

Please note that VARNISHD_SECONDARY_STORAGE must be defined as well, otherwise the secondary storage would not be available.

Example: instruct varnish to store in the secondary storage from the backend via custom header X-Cache-Bin:

VARNISH_STORAGE_CONDITION='beresp.http.x-cache-bin = "secondary"'

Installed Modules

Module	Varnish 6.0	Varnish 8.0
geoip	1.0.3
geoip2		latest
digest	1.0.3	1.0.3
cookie	6.0 latest	0.27.0
vsthrottle	6.0 latest	0.27.0
header	6.0 latest	0.27.0
saintmode	6.0 latest	0.27.0
softpurge	6.0 latest	0.27.0
tcp	6.0 latest	0.27.0
var	6.0 latest	0.27.0
xkey	6.0 latest	0.27.0
bodyaccess	6.0 latest	0.27.0

Modules can be imported as $VARNISH_IMPORT_MODULES=xkey,softpurge.

Default Behaviour

Caching Rules

• Only GET or HEAD requests are cached
• Backend responses with Set-Cookie header not cached
• Static files (see $VARNISH_STATIC_FILES) not cached by default, set $VARNISH_CACHE_STATIC_FILES to cache
• Error pages 404 and >500 not cached with grace period $VARNISH_ERRORS_GRACE
• All AJAX requests not cached
• Big files (larger than $VARNISH_BIG_FILES_SIZE) not cached

Cache Personification

White-listed cookies starting with VCKEY- followed by alphanumeric characters, underscores or hyphens are used to build cache hash. You can use such cookies to personify cache by a certain criteria, e.g. set VCKEY-lang to en or fr to cache different versions for English and French users.

On your backend you should check whether VCKEY- cookie exists, if it does generate a personified version of a page and do not set cookie again, otherwise it won't be cached on Varnish.

GeoIP

We identify client's two-letter country code (ISO 3166) and pass it to a backend in X-Country-Code header. If Varnish could not recognize the country the default value will be Unknown. You can optionally uniquify cache per country by setting $VARNISH_CACHE_PER_COUNTRY=1. We use GeoLite database from MaxMind.

If we see CloudFlare country code header we use it instead.

Currency

We use the country code to identify the currencxy and pass it to a backend in X-Currency header. You can optionally uniquify cache per currency by setting $VARNISH_CACHE_PER_CURRENCY=1.

We use data from IBAN to identify which country uses which currency, currently only USD and EUR supported.

Country codes for USD ($VARNISH_CURRENCY_USD_COUNTRY_CODES):

US|AS|BQ|IO|EC|SV|GU|HT|MH|FM|MP|PA|PW|PR|TL|TC|UM|VG|VI

Country codes for EUR ($VARNISH_CURRENCY_EUR_COUNTRY_CODES):

AD|AT|BE|CY|EE|FI|FR|GF|TF|DE|GP|GR|VA|IE|IT|LV|LT|LU|MT|MQ|YT|MC|ME|NL|PT|RE|BL|MF|PM|SM|SK|SI|ES|CE|CH|AX

Cache Flushing

• Purge and ban requests both use Varnish's ban method to flush cache and restricted by the purge key $VARNISH_PURGE_KEY (generated if missing). Use header X-VC-Purge-Key to pass the key for purge/ban requests
• Purge requests look up for exact match but ignores query params, you can change the method by setting X-VC-Purge-Method to regex or exact (respects query params)
• Additionally for ban requests cache flushed by Cache-Tags header (Drupal's case)
• If you want to allow unrestricted purge/ban requests in internal network specify a header via $VARNISH_PURGE_EXTERNAL_REQUEST_HEADER that exists only for external requests (e.g. X-Real-IP). If specified header is not set Varnish will skip purge key check

Miscellaneous

• Header X-VC-Cache set to HIT or MISS when varnish delivers content
• Cache hash includes host (or ip) and request protocol
• Varnish adds client's IP added to X-Forwarded-For
• Websocket requests supported
• Query params ($VARNISH_STRIP_PARAMS) stripped unless $VARNISH_KEEP_ALL_PARAMS is set
• Cookies ($VARNISH_STRIP_COOKIES) stripped unless $VARNISH_KEEP_ALL_COOKIES is set
• Hashes and trailing ? stripped from URL before passing to backend
• By default, cache mobile devices is identical. You can separate it by setting $VARNISH_MOBILE_SEPARATE_CASH or completely disable by setting $VARNISH_MOBILE_DISABLE_CASH. Regex $VARNISH_MOBILE_USER_AGENT used to identify mobile devices by User-Agent header
• Set one of the following headers from the backend to disable caching for a page:

  X-VC-Cacheable: NO
  Cache-control: private
  Cache-control: no-cache
  

• Set X-VC-Debug to show cache hashes and pass through header X-VC-DebugMessage
• BigPipe supported
• Secondary storage can be defined via $VARNISH_STORAGE_CONDITION
• ./vchealthz is a liveness endpoint with 204 response codes

Config Presets

You can use one of the following config presets to extend the default behaviour:

Drupal

Add VARNISH_CONFIG_PRESET=drupal to use this preset.

• Pages matching $VARNISH_DRUPAL_EXCLUDE_URLS will not be cached
• If a cookie from $VARNISH_DRUPAL_PRESERVED_COOKIES is set a page will not be cached. All other cookies stripped

VARNISH_DRUPAL_EXCLUDE_URLS:

Backslashes must be escaped as \\

^(/update\\.php|/([a-z]{2}/)?admin|/([a-z]{2}/)?admin/.*|/([a-z]{2}/)?system/files/.*|/([a-z]{2}/)?flag/.*|.*/ajax/.*|.*/ahah/.*)$

VARNISH_DRUPAL_PRESERVED_COOKIES:

Not affected by $VARNISH_KEEP_ALL_COOKIES

SESS[a-z0-9]+|SSESS[a-z0-9]+|NO_CACHE

WordPress

Add VARNISH_CONFIG_PRESET=wordpress to use this preset.

• Requests with ak_action|app-download query params or akm_mobile cookie not cached (Jetpack plugin)
• Strips replytocom= query param
• Use $VARNISH_WP_ADMIN_SUBDOMAIN if you have your admin on a subdomain to disable caching
• If a cookie from $VARNISH_WP_PRESERVED_COOKIES is set a page will not be cached. All other cookies stripped

VARNISH_WP_PRESERVED_COOKIES:

Not affected by $VARNISH_KEEP_ALL_COOKIES

PHPSESSID|wp-postpass_[a-z0-9]+|wordpress_[_a-z0-9]+|wordpress_logged_in_[a-z0-9]+|woocommerce_cart_hash|woocommerce_items_in_cart|wp_woocommerce_session_[a-z0-9]+|akm_mobile

PageSpeed Downstream Caching

This image contains implementation for modpagespeed downstream caching as described at https://www.modpagespeed.com/doc/downstream-caching. You can enable this behavior by specifying $VARNISH_PAGESPEED_SECRET_KEY to the value that matches DownstreamCacheRebeaconingKey in your Nginx/Apache config. This value will be used as PS-ShouldBeacon for 5% of hits and 25% of misses. Also, when static files cache enabled on Varnish, PS-CapabilityList will be set to fully general optimizations only to unify behavior for all browsers.

Orchestration Actions

make COMMAND [params ...]

commands:
    check-ready [host max_try wait_seconds delay_seconds]
    flush [host]
 
default params values:
    host localhost
    max_try 1
    wait_seconds 1
    delay_seconds 0

Deployment

Deploy Vinyl container to your own server via Wodby.