Skip to content
wodby
vinyl
Public

About

Vinyl Cache (Varnish) docker image

wodby.com/services/vinyl

Topics

alpinedockervarnishvinylvinyl-cache

Resources

Readme
MIT license
Activity
Custom properties

Stars

56 stars

Watchers

4 watching

Forks

30 forks
Report repository
BranchesTags

Latest commit

 

History

525 Commits

Folders and files

Repository files navigation

Vinyl Cache (Varnish Cache) Docker Container Image

Build Status Docker Pulls Docker Stars

Docker Images

Use image revision tags such as wodby/vinyl:9-rN to select a Wodby image revision. Major and minor tags use the repository release number, starting at r0. Full-version tags such as wodby/vinyl:9.1.0-r0 start at r0 for each exact upstream version. Every published versioned revision tag has a matching annotated Git tag pointing to its release commit. Existing tags remain available after support for their major or minor version ends. See release tags for available revisions and the image revision policy for upgrade guidance. Previously published image tags remain available.

Overview:

All images built for linux/amd64 and linux/arm64

Supported tags and respective Dockerfile links:

Upgrading from 8.0 to 9.1

Varnish Cache was renamed to Vinyl Cache in version 9. The image keeps the same environment variables, ports, /etc/varnish configuration directory and /var/lib/varnish volume, so most setups need no changes. Check the following before upgrading:

  • Programs were renamed: varnishd is now vinyld, varnishadm is vinyladm, varnishlog is vinyllog and so on. The old names still work in this image.
  • The X-Varnish response header is now X-Vinyl. The Server and Via headers report Vinyl-Cache.
  • Custom VCL must not use synthetic() or beresp.storage_hint: both were removed. Set resp.body or beresp.body instead of calling synthetic(). req.ttl is deprecated in favour of req.max_age.
  • IPv4-mapped IPv6 addresses such as ::ffff:192.0.2.1 are now matched by ACLs as IPv4 addresses.

See the upstream upgrade notes for 9.0 and 9.1.

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 Vinyl 9.1
geoip 1.0.3
geoip2 latest
digest 1.0.3 1.1.1
cookie 6.0 latest built-in
vsthrottle 6.0 latest 0.29.0
header 6.0 latest 0.29.0
saintmode 6.0 latest 0.29.0
softpurge 6.0 latest
tcp 6.0 latest 0.29.0
var 6.0 latest 0.29.0
xkey 6.0 latest 0.29.0
bodyaccess 6.0 latest 0.29.0
accept 0.29.0
str 0.29.0

Modules can be imported as $VARNISH_IMPORT_MODULES=xkey,header. On Vinyl 9.1 use the built-in purge module instead of 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 Wodby.

Building with pinned base images

Build with the Makefile to use the base image digests in base-images.mk. Local builds and CI resolve the same version and variant to the same multi-platform image. A version without a pin fails before the build starts.

When adding a supported base version or variant, add its image index digest to base-images.mk. For a custom build, override BASE_IMAGE with a complete repository:tag@sha256:... reference.

About

Vinyl Cache (Varnish) docker image

wodby.com/services/vinyl

Topics

alpinedockervarnishvinylvinyl-cache

Resources

Readme
MIT license
Activity
Custom properties

Stars

56 stars

Watchers

4 watching

Forks

30 forks
Report repository

Releases

Used by

Contributors

Languages