Skip to content
Varnish docker container image
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Add cache personification via VCKEY- cookies Dec 13, 2018
patches Remove subdir Dec 12, 2018
templates Pagespeed improvements and documentation Jun 17, 2019
tests Revert "Made VCKEY cookies availability on a backend" Mar 28, 2019
.alpine Rebuild against updated base image Jul 13, 2019
.gitignore Implement actions Mar 20, 2017
.travis.yml Update base image stability tag to 2.3.1 Jul 15, 2019
Dockerfile Add GeoIP database to repository Jan 16, 2019
GeoIP.dat.gz Add GeoIP database to repository Jan 16, 2019
LICENSE.md Add license file [skip ci] Aug 29, 2018
Makefile Update varnish to 6.0.3 Feb 19, 2019
README.md Update ToC Jun 17, 2019
docker-entrypoint.sh Revert "Return backwards compatible for deprecated env vars" Dec 18, 2018
release.sh

README.md

Varnish Docker Container Image

Build Status Docker Pulls Docker Stars Docker Layers

Docker Images

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

Overview:

Supported tags and respective Dockerfile links:

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 Version Imported
geoip 1.0.3
cookie latest
vsthrottle latest
header latest
saintmode latest
softpurge latest
tcp latest
var latest
xkey latest
bodyaccess latest

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

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 Varnish container to your own server via Wodby Wodby.

You can’t perform that action at this time.