Before you start using Symfony reverse proxy, you must change your kernel to use
EzSystems\PlatformHttpCacheBundle\AppCache instead of
Next, to use Symfony reverse proxy, follow the Symfony documentation.
Use Varnish or Fastly¶
As eZ Platform is built on top of Symfony, it uses standard HTTP cache headers. By default, the Symfony reverse proxy is used to handle cache. You can replace it with other reverse proxies, such as Varnish, or CDN like Fastly.
Using a different proxy is highly recommended as they provide better performance and more advanced features such as grace handling, configurable logic through VCL and much more.
Use of Varnish or Fastly is a requirement for a Clustering setup, as Symfony Proxy does not support sharing cache between several application servers.
Recommended VCL base files¶
For reverse proxies to work properly with your installation, you need to adapt one of the provided VCL files as the basis:
- Varnish VCL xkey example
- Fastly VCL can be found in
Configure Varnish and Fastly¶
The configuration of eZ Platform for using Varnish or Fastly requires a few steps, starting with configuring proxy.
Configure Symfony front controller¶
Set the following environment variable:
TRUSTED_PROXIES: String with trusted IP, multiple proxies can be configured with a comma, for example,
Add the trusted proxies to your configuration file:
Careful when trusting dynamic IP using
REMOTE_ADDR value or similar
On Platform.sh, Varnish does not have a static IP, like with AWS LB.
For this reason, the
TRUSTED_PROXIES env variable supports being set to value
REMOTE_ADDR, which is equal to:
When trusting remote IP like this, make sure your application is only accessible through Varnish. If it is accessible in other ways, this may result in trusting, for example, the IP of client browser instead, which would be a serious security issue.
Make sure that all traffic always comes from the trusted proxy/load balancer, and that there is no other way to configure it.
For more information about setting these variables, see Examples for configuring eZ Platform.
Update YML configuration¶
Next, you need to tell eZ Platform to use an HTTP-based purge client (specifically the FosHttpCache Varnish purge client),
and specify the URL that Varnish can be reached on (in
|Configuration||Parameter||Environment variable||Possible values|
||local, varnish, fastly|
||Array of URLs to proxies when using Varnish or Fastly (
||(Optional) For token-based authentication.|
||Service ID to authenticate with Fastly.|
||Service key/token to authenticate with Fastly.|
If you need to set multiple purge servers, configure them in the YAML configuration, instead of parameter or environment variable, as they only take single string value.
Example configuration for Varnish as reverse proxy, providing that front controller has been configured:
1 2 3 4 5 6 7 8 9 10
Invalidating Varnish cache using tokens
In setups where the Varnish server IP can change (for example, on Ibexa Cloud),
you can use token-based cache invalidation through
In such situation, use strong, secure hash and make sure to keep the token secret.
Ensure proper Captcha behavior¶
If your installation uses Varnish and you want users to be able to configure and use Captcha in their forms, you must enable sending Captcha data as a response to an Ajax request. Otherwise, Varnish does not allow for the transfer of Captcha data to the form, and as a result, users see an empty image.
To enable sending Captcha over Ajax, add the following configuration to
1 2 3 4 5 6
Custom Captcha block¶
If you created a custom Captcha block for your site by overriding the default file (
you must make the following changes to the custom block template file:
- change the name of the block to
- add a data attribute with a
As a result, your file should be similar to this example.
For more information about configuring Captcha fields, see Captcha field.
Use Fastly as HttpCache proxy¶
Configure Fastly in YML¶
1 2 3 4 5 6 7 8 9 10 11 12 13
Configure Fastly using environment variables¶
See the example below to configure Fastly with the
1 2 3 4 5 6 7
Configure Fastly on Platform.sh¶
If you use Platform.sh, it is recommended to configure all environment variables through Platform.sh variables. In eZ Platform, Varnish is enabled by default. To use Fastly, first you must disable Varnish
Get Fastly service ID and API token¶
To get the service ID, log in to http://fastly.com. In the upper menu, click the CONFIGURE tab. The service ID is displayed next to the name of your service on any page.
For instructions on how to generate a Fastly API token, see the Fastly guide.
The API token needs the
Examples for configuring eZ Platform¶
See below the most common configuration examples for the system, using environment variables.
Example for Varnish with the
1 2 3
Example for Apache with
1 2 3
Example for Nginx:
1 2 3
Example for Platform.sh:
You can configure environment variables through Platform.sh variables.
For HTTP cache, you will most likely only use this for configuring Fastly for production and optionally staging,
.platform.app.yaml to, for example, specify Varnish or Symfony proxy as default for dev environment.
Example for Apache with Varnish¶
1 2 3 4 5 6 7 8 9
Example for Nginx with Fastly¶
1 2 3 4 5 6 7 8 9
Understand stale cache¶
Stale cache, or grace mode in Varnish, occurs when: - Cache is served some time after the TTL expired. - When the back-end server does not respond.
This has several benefits for high traffic installations to reduce load to the back end. Instead of creating several concurrent requests for the same page to the back end, the following happens when a page has been soft purged:
- Next request hitting the cache triggers an asynchronous lookup to the back end.
- If cache is still within grace period, first and subsequent requests for the content are served from cache, and do not wait for the asynchronous lookup to finish.
- The back-end lookup finishes and refreshes the cache so any subsequent requests get a fresh cache.
By default, eZ Platform always soft purges content on reverse proxies that support it (Varnish and Fastly), with the following logic in the out-of-the-box VCL:
- Cache is within grace period.
- Either the server is not responding, or the request comes without a session cookie (anonymous user).
Serving grace is not always allowed by default because:
- It is a safe default. Even if just for anonymous users, stale cache can easily be confusing during acceptance testing.
- It means REST API, which is used by the Back Office, would serve stale data, breaking the UI.
Customizing stale cache handling
If you want to use grace handling for logged-in users as well, you can adapt the provided VCL to add a condition for opting out if the request has a cookie and the path contains REST API prefix to make sure the Back Office is not negatively affected.
If you want to disable grace mode, you can adapt the VCL to do hard instead of soft purges, or set grace/stale time to