Guide to Caching and Deployments with Varnish

Table of Contents :

Cache Principles - General Overview

Caches, especially Varnish, are highly effective for performance but add a layer of complexity that needs to be well understood to mitigate any side effects.

Regardless of PrestaShop considerations, it's important to understand how caching works :

  • On the first call, the cache is built.
  • On subsequent calls, the code isn't executed, and the cache is returned.
  • The cache needs to be cleared on certain events to stay up to date.

Its purpose is to accelerate a response by avoiding execution.

It must stay up to date either through intelligent cache clearing or cache expiration.

Different Types of Caches

In the case of PrestaShop, there are different types of caches, acting on :

  • Specific code snippets (e.g., module hooks)
  • Entire pages (e.g., Varnish, page cache ultimate)

They are implemented in different forms :

Varnish Cache Principle

  • It's configured on an HAProxy
  • At Influencing home / categories / products / CMS
  • For products/categories/CMS, the cache of the corresponding URL is cleared on each update
  • It caches the entire page
  • Requires dynamic executions for certain contextual blocks (e.g., cart)
  • Also caches static resources
  • Can differentiate between desktop/mobile cache

Cache Nesting

Caches operate at different levels. Understanding their nesting is crucial because clearing a cache at a higher level when the lower level is not up to date serves no purpose.
In its most comprehensive version, we can have this nesting stack :

For example, clearing Varnish while PageCache Ultimate still returns an old version of a page will have no effect.

Varnish - Checking Headers

To confirm if a response is from Varnish or not, you should check the response headers, e.g., HTML :

The x-cache header can take two values :

HIT : The cache responded
MISS : The cache was not queried; the resource is uncached

The x-cache-hits header shows how many times the cache was hit.
Clearing the cache of a page (via the back office or PHP code) will reset this header to 0.
If the value remains consistently at zero, the cache isn't being built.

The x-via header provides information about which HAProxy responded (e.g., ha1) to the browser and the PHP server that provided the response (e.g., Frt01)

Viewing Changes Despite Cache

  • Varnish doesn't take GET parameters into account. By adding ?nocache=1 to the page URL, we bypass Varnish cache for the HTML page. This must be confirmed in the response headers (x-cache = MISS)
  • If deploying a simple change shows the modification correctly, then only purging Varnish is necessary, as others seem to have already updated

Module - Eo_clearcache

This module allows clearing various cache levels.

It adds a visible interface in the menu: Advanced Settings > Performance

Functioning of Infrastructures

In the case of an infrastructure, understanding it is important.
It has 3 types of servers :

  • HAProxy: Receives requests, contains Varnish, queries the PHP server
  • PHP Server: Executes PHP code, queries the database server
  • Database Server: Contains the database

More information at :

What are the Best Practices for Production Deployment ?

Outside of cache issues, a production deployment should be secured by best practices :

  • Ensure your versioning system contains the current version of the codes
  • Ensure your versioning system contains the new version of the codes
  • Be able to provide the delivery differential
  • Be able to quickly revert to the state before deployment

How to Visualize a Content or Configuration Change Not Visible on the Front End ?

The "impact the front office" button clears caches related to content displays (i.e., without file modification) in the correct order. However, it doesn't clear Smarty compilation caches. If your site isn't optimized or experiences high traffic, it might experience slowdowns.

How to Deploy a Template Modification ? or Configuration Change ?

For this type of deployment, if PrestaShop is configured like this :

it will automatically detect and apply the modifications.

You'll still need to clear higher-level caches :

  • Additional cache module (e.g., PageCache ultimate)
  • Server cache (Varnish)

Before clearing Varnish, clear any additional cache module in place and test if the modification is visible without cache (see related paragraph). If it is, then clearing Varnish is sufficient; otherwise, another cache type is affecting below Varnish (which stands above all others, aside from remote caches like CDNs).

How to Deploy a CSS or JS ?

The procedure is similar to the previous one, except that if CCC (Combine, Compress and Cache) is enabled and PrestaShop doesn't version the compressed file name, or CCC isn't activated, CSS and JS resource modifications won't be visible by adding ?nocache=1 to the page URL.
Varnish caches static resources; if they don't change names, it won't detect the modification.

In this case, you can :

  • Clear only Varnish cache to rebuild static file caches
  • Add ?nocache=1 to the CSS file to verify your modifications

If CloudFlare is in place, it acts over Varnish, so the same issue arises, and you can clear its cache after Varnish.

Handling Deployments Involving Different Types of Files/Modifications

If your PrestaShop is properly configured, it will handle caches correctly.
In which case, you need to deploy your modifications and clear higher-level cache stacks in the correct order :

  • Additional cache module if present
  • Varnish server cache
  • External CDN if present

The "impact the front office" button clears caches in the correct order, except Smarty compilation caches. If your site isn't optimized or experiences high traffic, it might experience slowdowns.

The "clear all caches" button does the same but also clears the Smarty compilation cache, consuming more resources.

Don't use this feature too frequently; wait a few minutes before reusing it and monitor your traffic and performance simultaneously.

Note that the clearing order follows the order of different cache stacks, from the lowest to the highest :

  • Clearing PrestaShop and Smarty cache
  • Clearing the PageCache ultimate module cache if presentt
  • Clearing Varnish cache
  • Clearing CloudFlare cache if present

Is it Possible to Purge Varnish for a Single URL ?

Yes, absolutely. If a modification only affects one page, it's preferable to clear only that one (to avoid resetting the entire cache).

To do this, go to: Advanced settings > Performance
Click on the button to access advanced configuration :

This block :

allows you to clear the cache for the homepage or enter a URL and clear its cache.

NOTE: If you have multiple languages, remember to clear the URL for each language.

What about Maintenance Mode?

When activating or deactivating maintenance mode, to display either regular pages or the maintenance page based on the visitor's IP address, an automatic functionality is in place :

In maintenance mode, the Varnish server cache is disabled for HTML pages. When activating/deactivating maintenance, the Varnish server cache is cleared

The behavior for static resources remains the same (they are cached by the server).
For other aspects, deployment rules remain valid.

Infrastructure Considerations

In infrastructures, files may come from different servers. For example, the HTML might be requested from server #1, and the corresponding CSS might be requested from server #2.
The second server might not have executed the page yet and therefore hasn't generated the associated compressed CSS, for example.

Don't worry! Global cache clearing takes care of synchronization across your infrastructure.

In the case of using PageCache Ultimate, it should be configured in "memcached" mode so that its cache is shared across the infrastructure. takes care of this configuration aspect to make everything transparent for you.

However, there may be delays, and some pages might take a few seconds to get the CSS and JS, depending on the infrastructure's dissemination time. Generally, the timeframe is a few seconds, but it can be longer with Cloudflare (which communicates a maximum delay of 30 seconds on its interfaces but often takes less time in practice).

What to Do in Case of Trouble ?

In case of non-reproducible issues, (you notice the issue only on certain workstations, or a client reports a non-reproducible issue), it might be a problem occurring only on a specific server in the infrastructure.

he interface in the eo_clearcache configuration allows you to force a specific server :

And to check the servers one by one.

If loss of CSS or JS doesn't resolve after waiting a few seconds, you can contact our support, providing the following information :

  • The differential of your delivery, or the file causing the issue, or the identification of the line causing the issue (if possible)
  • Description of the issue (invisible modification, 404 error on a resource, etc.)
  • Identification of the problematic file (its URL)
  • In the case of an infrastructure: Screenshot of the response headers (prefixed with "x-") of the problematic resource

The CCC compression adds complexity, varying depending on your PrestaShop version and your software and server components. To temporarily resolve the issue, you can disable CCC compression and re-clear. But this should be temporary while understanding and resolving the issue.

In any case, if a global cache clearing doesn't resolve the issue: don't clear it multiple times; it will have the same effect and could harm your hosting. The key to success is understanding the issue in its context :

  • Am I or am I not in a Varnish server cache page ?
  • Am I or am I not in the context of an infrastructure ?
  • What is the cache level that isn't up to date ?

If you can't understand your issue, we're here to help. Providing precise technical elements will help us assist you.

If You Need to Disable Varnish Due to Any Unwanted Effects
In such a case, do not disable the eo_clearcache module because :

  • The server-side cache would still be active but with degraded software
  • The eo_clearcache module has several overrides, and under certain versions, PrestaShop will try to uninstall them, which could cause instabilities

To disable Varnish

  • Go to: Advanced settings > Performance
  • In the banner added by eo_clearcache, click on "access configuration"
  • Set Varnish activation to false :

  • Then re-add the restriction of dynamic modules by setting this configuration to true :

  • Finally, clear the Varnish cache to reset the server caches :

Your site will then run without Varnish, as the eo_clearcache module sends an instruction to the server not to apply Varnish cache.