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 ass-maxagefor a shared cache in front. Your owndeliver.vclcan 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,importa module orincludeanother file; return, inhash.vclanddeliver.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.
Thank you. Good to know it helped.
Thanks — tell us what was missing. Open a ticket from Support in the console, and we answer on the ticket. Open the console