Magento 2 Varnish Extension

November 28, 2018
Rafael Grigorian


The JetRails extension for Varnish® is a powerful tool that enables developers and Magento 2 site maintainers to manage Varnish Cache™ in a more effective manner. This extension supports both Magento 2 Open Source (CE) and Magento 2 Commerce (EE). There is support for environments with multiple Varnish servers configured. Features include strategies for purging all cache in Varnish, based on url path, or based on store view. Automatic cache purging on alterations to products, categories, and CMS pages stream line the process of making changes to your Magento store. Varnish Cache™ exclusion rules based on url path, route, module, controller, and action are used to bypass Varnish’s cache. Additionally, verbose HTTP response headers can be turned on to debug your store’s Varnish configuration whilst it is in development.

Disclaimer: All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them. Varnish is a registered trademark of Varnish Software AB and its affiliates. Magento and their logo are trademarks of Magento.

The MIT license

The JetRails Magento 2 extension for Varnish is licensed under the MIT license. If you would like to learn more, please see the details of the MIT license.

Installation process

Please read Installing Private Magento Modules Using Our MageRepo Repository for instructions on how to install this extension with MageRepo. Once you successfully add MageRepo to your Magento installation and are aware of the steps that are going to follow, run the following to install this extension:

$ composer require jetrails/magento2-varnish
$ php bin/magento setup:upgrade
$ php bin/magento cache:flush

Note: An additional step of logging out of your Magento’s backend may be required in order to refresh any altered ACL resources that the newly installed extension could have caused.

Setup process

Enable the extension

First thing that you need to do is install the Varnish configuration file that came with this extension onto all your servers that are running Varnish. If you have access to this extension’s GIT repository, then you can find this file at conf/default.vcl. There are two parts of the configuration file that need to be configured and then installed on every one of your servers that is running Varnish.

First, define where the backend is located. This will be the host and port of the server running PHP-FPM. Below the assumption that the backend serves on is made for the sake of example.

backend default {
    .host = "{{{backend_host:}}}";
    .port = "{{{backend_port:8080}}}";

Second, you will need to setup an ACL that will whitelist your backend and allow it to purge cache.

acl purge {

Note: If you are a JetRails customer, then all of the above steps is already done for you.

Next, log into the Magento backend. Navigate to Stores > Settings > Configuration through the menu and click on the JETRAILS > Varnish Cache™ tab. Once there you will see a drop down setting for Status in the General Configuration panel. Setting this option to Enabled will change the Magento’s caching application to Varnish Cache™ (thus enabling this extension), otherwise Magento’s caching application will be set to Built-in Cache (effectively disabling this extension).

Warning: This is not a tutorial on how to configure Varnish with Magento 2. In newer versions of Magento 2, there is more functionality that integrates with Varnish. For additional reference, consider reading Magento’s documentation on installing varnish for Magento and configuring multiple servers in Magento.

Configure Varnish servers

This extension supports configuring an array of Varnish servers. This means that you can configure this extension to communicate with multiple Varnish servers and purge cache on all of them at once. In the Varnish Servers text area in the General Configuration panel, you can enter as many Varnish servers as you want by entering each one in it’s own line in the format HOST:PORT. An example of such an entry can be

varnish servers configuration

Using debug mode

When Debug Mode is enabled, an extra HTTP parameter will be sent in the response header of every page. This parameter will be identified as JetRails-Hit-Miss and it’s value will always be either HIT or MISS. The values signify whether the visit to the page resulted in a HIT in Varnish Cache™ or if it resulted in a MISS in Varnish Cache™.

Enabling/disabling debug mode

To enable or disable Debug Mode, log into your Magento Backend and navigate to Store > Settings > Configuration using the menu. Under the JETRAILS > Varnish Cache™ tab you will see the option General Configuration > Debug Mode. Toggling this setting will either enable or disable Debug Mode.

turn on debug mode

Inspecting Varnish Cache™ status while in debug mode

Using Google Chrome, open the Developer Tools panel by clicking on the three dots on the top right of the browser window, using the menu, click on More Tools > Developer Tools. Once the developer tools panel opens, visit the Network tab. Once you refresh the page, you will see every resource that loads for the current page you are viewing. The very first item will be the request for the page itself. If you click on that item, you will see that more information is displayed. Looking under the Response Headers under the Headers tab, you will see that the JetRails-Hit-Miss parameter will be defined. You will also see headers that identify the current URL, path, and route. This is to make exclusion rules easier to write and are only shown when in debug mode. Additionally, if there was a cache miss that was caused by a cache exclusion rule, it will show up as a header stating what type of exclusion caused it to not cache as well as the actual rule itself. In the example below, the JetRails-No-Cache-Blame-Route header was set with the value search/search/term.

debug response headers

Purge Varnish Cache™

Once this extension is configured correctly with Varnish, it gives you the ability to purge your Varnish Cache™. You can get to the Varnish Cache™ Management panel by navigating to System > Tools > Cache Management through your Magento backend. You should see the panel right above the Additional Cache Management panel. The three different actions that you can take are outlined below:

purge varnish cache™

Purge by URL

Full URLs are not passed as a value, instead the path is passed as the value. That is, if you want to purge then you would only pass the path which would be /page. Whatever URL is passed will have to be matched exactly if Exact Match option is chosen. If the Sub-String option is chosen, then all URLs that contain the passed value as a substring will be purged.

Purge by store

This option will be populated with all the different store views that your Magento installation possesses. Each store view is associated with a domain name, which is interpreted from the store view’s associated Base URL value. This domain name will be used to purge all the URLs that contain said domain name.

Purge all

This option will simply purge all Varnish Cache™ entries that exist in all of the configured Varnish servers.

Automatic Varnish Cache™ purging

Purging Varnish Cache™ can optionally be triggered whenever a product, category, or CMS page gets saved/deleted. This extension then purges all Varnish Cache™ entries for all the URLs that are associated with the product, category, or CMS page. For example, when a product is updated, the product page and all rewrites that link back to the product page get purged. In addition, all category pages and their associated rewrites are also purged.

Different strategies are used based on what is being altered. The benefit of having automatic Varnish Cache™ purging is that every time something is changed, Varnish Cache™ is automatically purged, resulting in the latest instance being visible to your site’s visitors.

To toggle these setting, you can go to your Magento store’s backend and navigate to Stores > Settings > Configuration through the menu. Next, make sure you are in the JetRails > Varnish Cache™ tab. Under the Automatic Cache Purge section you will see the Product Save, Category Save, and the CMS Page Save settings.

automatic cache purge settings

Excluding paths & routes

If you wish to exclude certain URLs and/or routes from being cached by Varnish, you can do so though this extension. After logging into your Magento backend, navigate to Stores > Settings > Configuration. Under the JETRAILS > Varnish Cache™ tab and the Cache Exclusion Patterns panel, you will find the Exclude URL Paths and Exclude Routes settings.

cache exclusion patterns

Exclude paths

Paths will point to a single page and will not contain a domain name, therefore they will always begin with a forward-slash (/). Entering in one path per line will enable you to exclude multiple paths from being cached by Varnish. You can confirm that this path exclusion rule is working by enabling debug mode for this extension and opening up the Chrome Developer Tools to analyzing the response headers. If this exclusion rule successfully worked, then you should see that JetRails-Hit-Miss will be set to MISS and JetRails-No-Cache-Blame-Url will contain the rule that you set previously.

Exclude routes

Routes are defined within Magento and consist of the following format: route/module/controller/action. Excluding routes are left associative and therefore you are able to exclude a whole route by just specifying the route name. An example is if you enter admin then all requests to the admin route will be excluded from cache. Attaching more information to the route will more granularly help you exclude the routes that you want to exclude. You can confirm that this route exclusion rule is working by enabling debug mode for this extension and opening up the Chrome Developer Tools to analyzing the response headers. If this exclusion rule successfully worked, then you should see that JetRails-Hit-Miss will be set to MISS and JetRails-No-Cache-Blame-Route will contain the rule that you set previously.

Exclude paths (wildcard pattern)

This exclusion type is very similar to excluding by paths except you are able to specify a wildcard in the path. A ** will match across path segments, while * will match across the path segment it resides in. With the following pattern, /product/**/color-*, notice that the following paths will match: /product/foo/color-blue, /product/foo/bar/color-red, /product/foo/bar/baz/color-white. You can confirm that this path exclusion rule is working by enabling debug mode for this extension and opening up the Chrome Developer Tools to analyzing the response headers. If this exclusion rule successfully worked, then you should see that JetRails-Hit-Miss will be set to MISS and JetRails-No-Cache-Blame-Wildcard will contain the pattern that caused it to miss.

Exclude url (regexp pattern)

Regular expressions will match across a whole URL. This includes the schema, domain, path, & query parameters. Entering in one pattern per line will enable you to exclude using multiple patterns. If the pattern is invalid, it will be removed when saving. With the following pattern, /[?&]no-cache$/im, you can access pages that are not cached by attaching the no-cache query parameter as the last or first and only parameter. You can confirm that this url exclusion rule is working by enabling debug mode for this extension and opening up the Chrome Developer Tools to analyzing the response headers. If this exclusion rule successfully worked, then you should see that JetRails-Hit-Miss will be set to MISS and JetRails-No-Cache-Blame-RegExp will contain the pattern that caused it to miss.

Note: Be mindful of overmatching, since it is easily possible to exclude all urls with a single pattern. Use anchors (^$) when you can and try to be as specific as possible.

Magento CLI commands

This extension’s CLI commands can be executed through the Magento CLI binary. This can be achieved by going to your Magento installation directory and running the following command: php ./bin/magento <command>

Note: The <command> in the snippet above should be substituted with one of the commands below.


Communicates if the extension is enabled. This extension is enabled when Magento’s caching application is set to Varnish Cache™, it is disabled otherwise. Example command follows:

$ php ./bin/magento varnish:status

varnish:status:set <enable|disable>

When the required parameter is equal to enable, Magento’s caching application is set to Varnish Cache™. When disable is passed instead, the caching application is set to Built-in Cache. Some example commands are:

$ php ./bin/magento varnish:status:set enable
$ php ./bin/magento varnish:status:set disable

varnish:purge:url <URL>

Passing the URL as the required parameter, will purge all entries in cache from all configured Varnish servers that match the passed parameter exactly. An optional --substring flag can be passed to purge all entries in cache from all configured Varnish servers that contain the passed parameter as a substring. Some example commands are:

$ php ./bin/magento varnish:purge:url /checkout
$ php ./bin/magento varnish:purge:url --substring ?q=123

varnish:purge:store [STORE_VIEW_ID]

If the optional parameter is not passed, then all store views are displayed alongside their respective ids. This information can be used to pass a desired store view id as the optional parameter. If executed with a valid store view id as the parameter, the store view’s domain name will be used to purge Varnish Cache™. That is, all entries in cache from all configured Varnish servers will be purged that contain the selected store view’s configured domain name. Some example commands are:

Note: The domain name is extracted from the store view’s configured base url. This value can be inspected/configured by going to Stores > Configuration > General > Web > Base URLs > Base URL through your Magento’s backend. Make sure your desired store view is chosen when on the configuration page.

$ php ./bin/magento varnish:purge:store /checkout
$ php ./bin/magento varnish:purge:store 1


This command takes no parameters. If executed, it will purge all entries in cache from all configured Varnish servers. Example command is as follows:

$ php ./bin/magento varnish:purge:all

Additional support

For additional support or inquiries, please feel free to reach out to us by phone or email. Any found bugs or feature requests can also be communicated to us through email. This extension is currently in beta and any feedback would be extremely valuable.

Call us at 1(888) 997-2457 or send an email to [email protected].