Skip to content

wodby/varnish

BranchesTags

Repository files navigation

Varnish Docker Container Image

Build Status Docker Pulls Docker Stars

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:

All images built for linux/amd64 and linux/arm64

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 ✓
digest 1.0.2
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
  • ./vchealthz is a liveness endpoint with 204 response code

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.

About

Varnish docker container image

wodby.com/stacks/varnish

Topics

docker alpine varnish

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

60 stars

Watchers

6 watching

Forks

29 forks
Report repository

Releases

111 tags

Packages

No packages published

Contributors 8

Languages