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:

  1. Install Varnish and test it by accessing any Commerce page to see if you are getting HTTP response headers that indicate Varnish is working.

  2. Install the Commerce software and use the Admin to create a Varnish configuration file.

  3. Replace your existing Varnish configuration file with the one generated by the Admin.

  4. Test everything again.

    If there is nothing in your <magento_root>/var/page_cache directory, you have successfully configured Varnish with Commerce!

NOTE
  • 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:

  • Varnish does not support SSL

    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 the backend 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 Commerce
  • default.vcl configuration for Varnish generated using the Admin
INFO
This topic covers only the default options in the preceding list. There are many other ways to configure caching in complex scenarios (for example, using a Content Delivery Network); those methods are beyond the scope of this guide.

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 first time a request is made for a cacheable object, Varnish delivers it to the browser

The preceding example shows a request for the storefront main page (m2_ce_my). CSS and JavaScript assets are cached on the client browser.

NOTE
Most static assets have an HTTP 200 (OK) status code, indicating the asset was retrieved from the server.

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.

The next time the same object is requested, assets load from the local browser cache

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.

The ETag makes it easier to determine whether a static asset has changed or not

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 HTTP 304 (Not Modified) response code indicates the static asset in the local cache is the same as on the server

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.

Previous pageUse Redis for session storage
Next pageInstall Varnish

Commerce