Skip to main content
Open console

Vinyl Cache (Varnish)

Caches whole responses in front of your site, so a hit never reaches it

4 min read

Varnish Cache, named Vinyl Cache from 9.0 (the service's id is vinyl), caches whole responses in front of whatever answers for the site. That is Nginx for a PHP application, the application itself for Node.js, Go, Python, Ruby or Rust, or the Nginx its repository put in front of it.

It is not offered to a static site. It can sit on the web server or on a machine of its own, and with more than one web server it spreads the misses across all of them. See Shapes.

What is cached

It caches what your application says may be cached:

Response Kept
Sent with Cache-Control: max-age That long
Sent without Two minutes, unless you set VARNISHD_PARAM_DEFAULT_TTL
  • Browsers are told less. A page or an API answer Varnish may keep for longer than five minutes reaches them as max-age=300, with what your application said kept as s-maxage for a shared cache in front. Your own deliver.vcl can set a different one.
  • A page that is past its time may still be served for a short while as a fresh copy is fetched behind it.

A request has 60 seconds to start answering through Varnish, whatever Nginx and PHP allow. Work that takes longer belongs in a worker.

Purging

Your application finds it at VARNISH_HOST, port 6081. That variable and VARNISH_PURGE_KEY are in the environment.

Purge sent from Needs
Inside the stack No key
Outside VARNISH_PURGE_KEY in an X-VC-Purge-Key header

For Drupal's purger, see the snippet.

From your own computer, vallic tunnel <env> varnish opens it on http://127.0.0.1:6081. See Tunnels.

The visitor's country

Requests reach your application with the visitor's country in X-Country-Code, a two-letter code. VARNISH_CACHE_PER_COUNTRY keeps a copy of each page per country.

Behind Cloudflare it is Cloudflare's own answer. Otherwise it is looked up in DB-IP's IP to Country Lite database, under the Creative Commons Attribution licence: a site that shows the country or acts on it should credit IP Geolocation by DB-IP.

Rules of your own

Four files in your repository add to the cache policy; none replaces it:

File Added to
.vallic/varnish/recv.vcl vcl_recv: what to do with a request, such as a path never to cache or a cookie to ignore
.vallic/varnish/hash.vcl vcl_hash: what else the cache key varies on, with hash_data(), such as a header, a cookie or a currency
.vallic/varnish/backend-response.vcl vcl_backend_response: what to do with an answer, such as a lifetime for one route or a header to keep
.vallic/varnish/deliver.vcl vcl_deliver: headers on the way out, one to add or one to take off

Each is read from the commit of the release you deployed. A change takes effect with the deploy that carries it, not when you push. A rollback brings back the rules of the release you roll back to.

Each file holds rules for that one subroutine, at most 8 KB. A file may not:

  • declare a backend, define vcl_init, import a module or include another file;
  • return, in hash.vcl and deliver.vcl.

A file that does is left out, and the policy runs without it. The assembled policy is compiled before it replaces the one running, and a policy that does not compile is not loaded.

Versions

Version Status
8.0 Supported, and the default
9.1 Supported

Pin the version, not the build: name 8.0 and the platform matches it to the current build, so a security rebuild reaches you without anybody editing a repository.

What you can change

In vallic.yaml — what each one does is on Service settings:

services:
  - vinyl:
      version: '8.0'
      environment:
        VARNISHD_PARAM_DEFAULT_TTL: …
        VARNISH_BACKEND_GRACE: …
        VARNISH_CACHE_PER_COUNTRY: …
        VARNISH_MOBILE_SEPARATE_CASH: …
        VARNISH_KEEP_ALL_PARAMS: …

Anything not on this list refuses the deploy, naming the variable — rather than being accepted and quietly ignored.

Versions

8.0 and 9.1. 8.0 is what a stack gets unless it names another, and it has had its last release, 8.0.2. 9.1 is Vinyl Cache's current line. To move, name it under services in vallic.yaml:

services:
  - vinyl: '9.1'

The platform's own policy runs on both. A rule of your own written for 8.0 may not compile on 9.1: try the move on a preview environment first.

Where the new version refuses your rules, the move is not made:

  • The environment goes on running 8.0.
  • Cache rules on its Resources tab says what the compiler said.

Fix the rule and deploy, or name 8.0 again. Until then the environment's other changes wait as well.

The cache starts empty on the new version, as after any restart.

Need a hand?

Open a ticket from Support in the console. We answer on the ticket.

Open the console How support works