• Documentation >
• Content management >
• Images >
• Fastly Image Optimizer

Fastly Image Optimizer (Fastly IO)

The Fastly Image Optimizer (Fastly IO) is an external service that provides real-time image optimisation for multiple input and output formats. It serves and caches image requests from your origin server, making your website faster and more efficient.

To be able to configure this feature, you need Fastly IO subscription.

Enable shielding

To use Fastly Image Optimizer, you need shielding. To enable it, follow steps in Fastly documentation, Enabling and disabling shielding.

Before proceeding, make sure that you have the snippet_re_enable_shielding.vcl configuration file added to your project:

set var.fastly_req_do_shield = (req.restarts <= 2);

# set var.fastly_req_do_shield = (req.restarts > 0 && req.http.accept == "application/vnd.fos.user-context-hash");
set req.http.X-Snippet-Loaded = "v1";

You can add it using Fastly CLI:

- fastly vcl snippet create --name="Re-Enable shielding on restart" --version=active --autoclone --priority 100 --type recv --content=vendor/ibexa/fastly/fastly/snippet_re_enable_shielding.vcl
- fastly service-version activate --version=latest

Next, you need to choose the Shield location from the Shielding menu in Fastly web interface as specified in Fastly IO documentation.

VCL configuration

To manipulate your Fastly VCL configuration directly from the command line, you need to:

• install Fastly CLI,
• define FASTLY_SERVICE_ID and FASTLY_KEY environmental variables,
• set restrictions on the optimiser by using ibexa_image_optimizer.vcl:

# Restrict optimizer by file path and extension
if (req.url.ext ~ "(?i)^(gif|png|jpe?g|webp)$") {
    if (req.url.path ~ "^/var/([a-zA-Z0-9_-]+)/storage/images") {
        set req.http.x-fastly-imageopto-api = "fastly";
    }
}

This is an example VCL snippet uploaded by using the vcl_recv hook:

fastly vcl custom create --name="Ibexa VCL" --main --version=latest --autoclone  --content=vendor/ibexa/fastly/fastly/ez_main.vcl
fastly vcl snippet create --name="Shielding" --version=active --autoclone --type recv --content=vendor/ibexa/fastly/fastly/snippet_re_enable_shielding.vcl

Fastly passes requests through the image optimizer by adding the x-fastly-imageopto-api header in vcl_recv. You need to restrict the optimizer by file path and extension to only apply to image requests:

if (req.url.ext ~ "(?i)^(gif|png|jpe?g|webp)$") {
    if (req.url.path ~ "^/var/([a-zA-Z0-9_-]+)/storage/images") {
        set req.http.x-fastly-imageopto-api = "fastly";
    }
}

You can define what image formats will be included, for example: gif|png|jpe?g|webp and which paths should be used as a source of images, for example: ^/var/([a-zA-Z0-9_-]+)/storage/images. For more configuration options, see Enabling image optimization.

After you save this snippet or create your own, you can upload it from the command line using:

fastly vcl snippet create --name="Shielding" --version=active --autoclone --type recv --content=vendor/ibexa/fastly/fastly/snippet_re_enable_shielding.vcl

Define SiteAccess for Fastly IO

Fastly IO configuration is SiteAccess aware. You can define what handler should be used for a specific SiteAccess under variation_handler_identifier. You need to set it up as fastly, so Fastly IO can generate all image links. By default, it is set as alias, and it points to a built-in image optimizer. You can also set up a custom handler if your setup requires it.

ibexa:
    system:
        my_siteaccess:
            variation_handler_identifier: 'fastly'

You can also use environmental variables to configure a specific handler for a SiteAccess. See the example below to configure it with the .env file:

IBEXA_VARIATION_HANDLER_IDENTIFIER="fastly"

Image configuration

When you define image variation keys for Fastly IO, keep in mind that they should reflect variations in your original setup. The built-in image optimizer serves as backup to Fastly IO in case of misconfiguration, so it needs to be able to serve the same image variations.

Fastly IO image filters are not compatible with our built-in filters, so you will not be able to reflect your original filters accurately with Fastly. The script below will help you find replacement filters within Fastly configuration for the basic filters. For more optimization options on Fastly side, see Fastly IO reference.

To generate your original image configuration run:

php bin/console ibexa:fastly:migrate-configuration

Paste the configuration to config/packages/ibexa.yaml to define the same variations for Fastly IO:

ibexa:
    system:
        default:
            fastly_variations:
                reference:
                    reference: original
                    configuration:
                        width: 600
                        height: 600
                        fit: bounds
                small:
                    reference: reference
                    configuration:
                        width: 100
                        height: 100
                        fit: bounds
                tiny:
                    reference: reference
                    configuration:
                        width: 30
                        height: 30
                        fit: bounds
                medium:
                    reference: reference
                    configuration:
                        width: 200
                        height: 200
                        fit: bounds
                large:
                    reference: reference
                    configuration:
                        width: 300
                        height: 300
                        fit: bounds
                gallery:
                    reference: original
                    configuration: { }
                ezplatform_admin_ui_profile_picture_user_menu:
                    reference: reference
                    configuration:
                        width: 30
                        height: 30
                        fit: bounds
                        crop: '30,30,x0,y0'

You can select defined image variations during Content item creation in the image options. Variations can include different sizing options and other filters that are applied to the image.