Process overview
This topic discusses how to initially install Varnish with a minimal set of parameters and test that it works. Then export a Varnish configuration from the Commerce Admin and test it again.
The process can be summarized as follows:
-
Install Varnish and test it by accessing any Commerce page to see if you are getting HTTP response headers that indicate Varnish is working.
-
Install the Commerce software and use the Admin to create a Varnish configuration file.
-
Replace your existing Varnish configuration file with the one generated by the Admin.
-
Test everything again.
If there is nothing in your
<magento_root>/var/page_cache
directory, you have successfully configured Varnish with Commerce!
-
Except where noted, you must enter all commands discussed in this topic as a user with
root
privileges. -
This topic is written for Varnish on CentOS and Apache 2.4. If you are setting up Varnish in a different environment, some commands may be different. Consult Varnish documentation for more information.
Known issues
We know of the following issues with Varnish:
-
As an alternative, use SSL termination or an SSL termination proxy.
-
If you manually delete the contents of the
<magento_root>/var/cache
directory, you must restart Varnish. -
Possible error installing Commerce:
Error 503 Service Unavailable Service Unavailable XID: 303394517 Varnish cache server
If you experience this error, edit
default.vcl
and add a timeout to thebackend
stanza as follows:backend default { .host = "127.0.0.1"; .port = "8080"; .first_byte_timeout = 600s; }
Overview of Varnish caching
Varnish caching works with Commerce using:
nginx.conf.sample
from the Magento 2 GitHub repository.htaccess
distributed configuration file for Apache provided with Commercedefault.vcl
configuration for Varnish generated using the Admin
On the first browser request, cacheable assets are delivered to the client browser from Varnish and cached on the browser.
In addition, Varnish uses an Entity Tag (ETag) for static assets. The ETag provides a way to determine when static files change on the server. As a result, static assets are sent to the client when they change on the server—either on a new request from a browser or when the client refreshes the browser cache, typically by pressing F5 or Control+F5.
More detail is provided in the sections that follow.
Caching by browser request
This section uses a browser inspector to show how assets are delivered to the browser in the first request and afterward loaded from the local browser cache.
First browser request
nginx.conf.sample
and .htaccess
provide options for client caching. When the first request is made from a browser for a cacheable object, Varnish delivers it to the client.
The following figure shows an example using a browser inspector:
The preceding example shows a request for the storefront main page (m2_ce_my
). CSS and JavaScript assets are cached on the client browser.
Second browser request
If the same browser requests the same page again, these assets are delivered from the local browser cache, as the following figure shows.
Note the difference in response time between the first and second request. Again, static assets have a 200 (OK) response code because they are delivered from local cache for the first time.
How Commerce uses Etag
The following example shows response headers for a particular static asset.
calendar.css
has an ETag response header which means the CSS file on the client browser can be compared to the one on the server.
In addition, static assets are returned with a 304 (Not Modified) HTTP status code, as the following figure shows.
The 304 status code occurs because the user invalidated their local cache and the content on the server did not change. Because of the 304 status code, the static asset content is not transferred; only HTTP headers are downloaded to the browser.
If the content changes on the server, the client downloads the static asset with an HTTP 200 (OK) status code and a new ETag.