Before you start using Symfony reverse proxy, you must change your kernel to use
Ibexa\Bundle\HttpCache\AppCache instead of
Next, to use Symfony reverse proxy, follow the Symfony documentation.
Using Varnish or Fastly¶
As Ibexa DXP 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.
VCL base files¶
For reverse proxies to work properly with your installation, you need to add the corresponding VCL files for your HTTP Cache.
- Varnish VCL xkey example
- Fastly can be found in
vendor/ibexa/fastly/fastly. You must install the following to use Fastly:
ez_main.vclas the main custom VCL
ez_user_hash.vclas another custom VCL
.vcl files work both with Fastly Shielding enabled and without it.
If you decide to use Fastly VCL, consider using Fastly CLI with it to manage VCL files from the command line.
To learn more, see Prepare to use Fastly locally and Introduction to Fastly CLI.
Support for Fastly Shielding was added in Ibexa DXP v3.3.24 and v4.1.6
Configure Varnish and Fastly¶
The configuration of Ibexa DXP for using Varnish or Fastly requires a few steps, starting with configuring proxy.
Failing to configure reverse proxies correctly may introduce several problems, including, but not limited to:
- Ibexa DXP generating links with a wrong protocol schema (HTTP instead of HTTPS) if HTTPS termination is done before the web server due to the
X-Forward-Protoheaders being ignored
- Ibexa DXP generating links with wrong port numbers due to the
X-Forward-Portheaders being ignored
- Back Office showing the login screen because JWT tokens are not accepted due to the
X-Forward-Forheaders being ignored
Configure Symfony front controller¶
You need to consider your
TrustedProxy configuration when you use Symfony behind a load balancer or a reverse proxy.
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.
When using Fastly, you need to set
trusted_proxies according to the IP ranges used by Fastly.
You don't have to set
trusted_proxies when using Fastly on Platform.sh.
The Platform.sh router automatically changes the source IP of requests coming from Fastly,
replacing the source IP with the actual client IP and removing any
X-FORWARD-... header in the request before it reaches Ibexa DXP.
For more information about setting these variables, see Configuration examples.
Update YML configuration¶
Next, you need to tell Ibexa DXP to use an HTTP-based purge client (specifically the FosHttpCache Varnish purge client), and specify the URL that Varnish can be reached on:
|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:
1 2 3 4 5 6
Update 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 Ibexa DXP, 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
See below the most common configuration examples for the system, using environment variables.
Example for Varnish with the
Example for Apache with
Example for Nginx:
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.
Apache with Varnish¶
1 2 3 4 5 6 7 8 9
Nginx with Fastly¶
1 2 3 4 5 6 7 8 9
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, Ibexa DXP 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