# Fastly Image Optimizer (Fastly IO)

The Fastly Image Optimizer (Fastly IO) is an external service that provides real-time image optimization 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](https://www.fastly.com/documentation/guides/full-site-delivery/about-fastly-image-optimizer/).

## Enable shielding

To use Fastly Image Optimizer, you first need a [working setup of Ibexa DXP and Fastly](https://doc.ibexa.co/en/latest/infrastructure_and_maintenance/cache/http_cache/reverse_proxy/#using-varnish-or-fastly) with shielding enabled. To enable shielding, follow the steps in [Fastly Developer Documentation](https://www.fastly.com/documentation/guides/concepts/shielding/#enabling-and-disabling-shielding). Remember to choose a shield location from the **Shielding** menu, as described in [Fastly User Documentation](https://www.fastly.com/documentation/guides/getting-started/hosts/shielding#enabling-shielding).

## VCL configuration

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

- [install Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/#installing),
- define `FASTLY_SERVICE_ID` and `FASTLY_KEY` environmental variables,
- set optimizer restrictions by using the `ibexa_image_optimizer.vcl` file:

```
# 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";
    }
}
```

You can customize what image formats are 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](https://www.fastly.com/documentation/reference/io/#enabling-image-optimization).

To apply your modifications or use the default configuration as-is, you can upload the `.vcl` file from the command line:

```
fastly vcl snippet create --name="Ibexa Image Optimizer" --version=active --autoclone --type recv --content=vendor/ibexa/fastly/fastly/ibexa_image_optimizer.vcl
fastly service-version activate --version=latest
```

For more information about Fastly configuration and CLI usage examples, see [Configure and customize Fastly](https://doc.ibexa.co/en/latest/infrastructure_and_maintenance/cache/http_cache/fastly/index.md).

## 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` [configuration key](https://doc.ibexa.co/en/latest/administration/configuration/configuration/#configuration-files). You need to set it up as `fastly`, so Fastly IO can generate all image links. By default, it's 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 aren't compatible with Ibexa built-in filters, so you aren't able to reflect your original filters accurately with Fastly. The script below helps you find replacement filters within Fastly configuration for the basic filters. For more optimization options on Fastly side, see [Fastly IO reference](https://www.fastly.com/documentation/reference/io/).

To generate your original image configuration run:

```
php bin/console ibexa:fastly:migrate-configuration
```

Paste the following configuration 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.