Imaginary

You can easily setup your own image resize / convert service using Imaginary. For example: you can easily serve webp format images for browsers who support it or compress / resize images by just changing a query parameter.

For a full list of api endpoints, see https://github.com/h2non/imaginary.

When using Imaginary in production, you will quickly realize there is no caching implemented in the service. So every request results in a new resize / convert of the image resulting in very high load and slow image response times. For this we created a Docker image that combines Imaginary with Varnish.

Installation

We will be using the Hipex CLI docker commands to run the container. For the remaining of this tutorial we assume you are familiar with the docker basics.

Step 1

Create your docker configuration file in ~/domains/example.com/imaginary/docker-compose.yml.

version: "3.2"

services:
    imaginary:
        image: registry.hipex.cloud/tools/imaginary:v1.2.1
        restart: "always"
        environment:
            VARNISH_CACHE_SIZE: "5g"
            # Workaround for issue https://github.com/h2non/imaginary/issues/198
            MALLOC_ARENA_MAX: "2"
        ports:
        - "19000:9000" # Varnish port
        # - "19001:9001" Optional direct imaginary port without caching

Now the service can be started using docker:compose:up.

cd ~/domains/example.com/imaginary/
hipex docker:compose:up --detach

Step 2

We recommend creating a new pointer to your application with something like cdn.example.com so you can redirect all traffic to your imaginary service. After creating the pointer you can create a Nginx proxy configuration in ~/domains/example.com/var/etc/cdn.example.com-443/proxy.nginx.conf

location  ~* ^\/.* {
    proxy_pass  http://127.0.0.1:19000;

    # Default proxy settings
    proxy_connect_timeout	6000;
    proxy_send_timeout      6000;
    proxy_read_timeout      6000;
    send_timeout            6000;

    proxy_set_header Host $host;
}

Configuration

For configurationsl, environment variables are used. These can be set up in docker-compose.yml.

• VARNISH_CACHE_SIZE Maximum cache size, defaults to 25g
• VARNISH_ENABLE_EXPORTER Enables prometheus exporter on port 9131, default false.
• IMAGINARY_ARGUMENTS Set extra imaginary arguments for example -allowed-origins https://*.example.com.
• IMAGINARY_CONCURRENCY Set the imaginary concurrency parameter, default 20.
• IMAGINARY_TTL Set the imaginary cache ttl parameter, default 31556926.

The imaginary startup command used:

imaginary \
    -p 9001 \
    -enable-url-source \
    -concurrency ${IMAGINARY_CONCURRENCY} \
    -http-cache-ttl ${IMAGINARY_TTL} \
    "${IMAGINARY_ARGUMENTS}"

Purging cache

You can purge all cache objects by restarting the docker container or executing a request with the http PURGE method.

curl -XPURGE https://cdn.example.com/convert?url=https%3A%2F%2Fwww.example.com%2Fsome-image.png&type=auto