/
Pack Hosting Panel

Imaginary

How can you setup your own image resizing & conversion service with Imaginary


With Imaginary, you can easily setup your own image resize / convert microservice. For example: you can easily serve webp format images to browsers who support it or compress / resize images with just changing a query parameter. For a full list of api endpoints please have a look at 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 container that combines imaginary with varnish.

Installation

We will be using the Hipex CLI docker commands to run the container. For the rest 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"
        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 configurations environment variables are used. These are setup 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