Configure and customize Fastly¶
You can configure Fastly by using API calls or through the Fastly Web Interface. Fastly provides a Fastly CLI for configuring Fastly through its API.
Ibexa Cloud is delivered with Fastly preconfigured. It means that you don't have to do any changes to the Fastly configuration to make your site work. The information provided here is only applicable if you want to change the default Fastly configuration on Ibexa Cloud, or if you are not using Ibexa Cloud and want to configure Fastly to work with Ibexa DXP on premise.
The Fastly Web Interface is not available for Ibexa Cloud
It's recommend for Ibexa Cloud customers to use the Fastly CLI instead of using the Fastly API directly with
curl, and so on.
Disable Varnish when you use Fastly
Varnish is automatically provisioned on Ibexa Cloud. Varnish needs to be disabled on all environments that use Fastly. See documentation on how to do that.
Prepare for using Fastly locally¶
These steps are not needed when you use Ibexa Cloud, because Fastly is preconfigured in it.
Get Fastly credentials from Ibexa Cloud installation¶
To use Fastly CLI or Fastly API directly, you need to obtain the credentials for your site. To obtain the credentials, connect to your Fastly-enabled environment (for example, production or staging) through SSH and run the following command:
1 2 3
These credentials are different for your production and staging environments. When you configure the Fastly CLI, use the credentials for the environment that you want to change.
Different environment variable names between products
When you configure Fastly CLI, you use the
FASTLY_API_TOKEN variable to store the token, while with Ibexa DXP you use
FASTLY_KEY for the same purpose.
Quickly configure Fastly for use with Ibexa DXP¶
Use the commands below to install VCL configuration required for running Fastly with Ibexa DXP. You also need to set up domains, HTTPS and origin configuration (not covered here). All commands are explained in detail below:
1 2 3 4
Quick introduction to Fastly CLI¶
Fastly configuration is versioned, which means that when you alter the configuration, you create a new version and activate it. If needed, you can revert the configuration to one of previous versions at any point.
List configuration versions¶
1 2 3 4 5 6 7 8 9 10
In the example above, version 8 is used (ACTIVE=true).
Create new configuration version¶
A version that is ACTIVE cannot be modified. To change the configuration, you need to create a new version:
Clone the current active version:
Clone a particular version:
Clone the newest version:
Most Fastly CLI commands have the
In addition to a specific version number, the
--version parameter always supports aliases like
Most Fastly CLI commands that alter the config also support the
With such commands, when you use the
--autoclone parameter, calling
fastly service-version clone is no longer needed.
Activate a version with this command:
View and modify VCL configuration¶
Fastly configuration is stored in Varnish Configuration Language (VCL) files.
You can change the behaviour of Fastly by uploading custom VCL files.
Ibexa DXP ships with two VCL files that need to be enabled for Fastly to work correctly with the platform;
ez_user_hash.vcl (located in
.vcl files for specific version¶
1 2 3 4
ez_main.vcl for specific version¶
1 2 3 4 5 6 7 8 9 10 11 12 13
Provide description for specific version¶
For each version, you can provide a description that explains what changed in that version:
List descriptions for all versions¶
You can list the descriptions by adding the
-v) option to the
service-version list command:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
Modify Fastly configuration¶
You can modify the existing Fastly configuration, for example, by uploading a modified
Create a new version based on the one that is currently active, and upload the file:
Provide a description of the change in Fastly's version system:
Activate the new version:
You can also add VCL code to the Fastly configuration without modifying the custom
.vcl files directly.
You do it by creating snippets.
It is recommended that you use snippets instead of changing the VCL files provided by Ibexa DXP as much as possible, which makes it easier to upgrade the Ibexa DXP VCL configuration later.
When you use snippets, the snippet code is injected into the VCL where the
#FASTLY ... macros are placed.
For example, if you create a snippet for the
recv subroutine, it is injected into the
ez_main.vcl file, the
#FASTLY recv is found.
List available snippets for specific version¶
1 2 3
As of version 3.3.24, 4.1.6 and 4.2.0, Ibexa DXP also requires one snippet to be installed, in addition to the custom VCLs
ez_user_hash.vcl. That snippet is by default named
Re-Enable shielding on restart.
Get details of installed snippets¶
vcl snippet list command with the
--verbose option to get information such as: priority, which subroutine it is attached to (
vcl_fetch etc.) and the code itself.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
You can also get the same details for a particular snippet using the
vcl snippet describe command.
Get specific snippet¶
Update existing snippet¶
Get diff between two versions¶
You can easily view the diff between two different versions by using the Fastly web interface. Unfortunately, Fastly CLI does not support this functionality. However, Fastly API and GNU diff can help you get an identical result.
Use the Fastly API to download the generated
.vcl file. It includes the VCL configuration that Fastly generates
based on all the configuration settings (from all custom
.vcl files, snippets, and origin configuration).
The example below extracts the generated VCL for version no. 11 of some service:
Next, you need to edit
generated_vcl_11_json_only in your favourite editor, remove anything before the json data and save.
Then, follow the same steps again for version no. 12 (or whatever version you want to diff version 11 against).
\n in the files to get human-readable diffs:
Finally, you can use GNU diff to get a readable diff of the two versions:
Enable basic-auth on Fastly¶
To enable basic-auth, use Fastly documentation as an example.
Follow the steps below.
Usernames and passwords can be stored inside the VCL file, but in this case credentials are stored in a dictionary.
To make this example work, you must run Ibexa DXP in version 3.3.16 or later, or 4.5.
Create and activate dictionary¶
Fastly configuration includes a dictionary named
Using a dictionary instead of storing usernames directly in a
.vcl file is beneficial, because you can add or remove records without having to create and activate new configuration versions.
Get dictionary ID¶
To add users to the dictionary, first get the dictionary ID.
1 2 3 4 5 6 7 8 9
In the example above, the ID is
Create record in dictionary¶
Add username and password to the dictionary:
List dictionary records¶
You can list the records from a dictionary by using the following command:
Now your dictionary stores new username and password. The next thing to do is to alter the Fastly VCL configuration
and add the basic-auth support.
This example uses snippets, so that no changes are needed in the
.vcl files that are shipped with Ibexa DXP.
You need two snippets, store these as files in your system:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
To enable basic-auth for one domain only, alter
Install the snippets with the following Fastly CLI command:
1 2 3