An image proxy that can resize images from an upstream server and store the source and target images locally for quick response times. In a Kubernetes cluster with multiple replicas ixy uses rendezvous hashing (replication factor 2) to route requests to owner pods instead of copying caches between replicas.

Quickstart with KinD

$ ./scripts/quickstart.sh
$ curl -o /dev/null \
       -s \
       -w 'Establish Connection: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n' \
       http://127.0.0.1:8080/200/200/300/300

Quickstart with Docker

$ docker compose up &
$ curl -o /dev/null \
       -s \
       -w 'Establish Connection: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n' \
       http://127.0.0.1:8080/200/200/300/300

Usage

The URL are parsed as followed:

http://127.0.0.1:8080/200/200/g:n/f:webp/300/300
                     |___|___|___|______|_______|
                       |   |   |     |      |
target image width ----+   |   |     |      |
target image height -------+   |     |      |
gravity for crop: north -------+     |      |
output format: WebP -----------------+      |
source image path --------------------------+

If image width or height is set to 0 the aspect ratio is retained. If both are 0 the source image is returned, scaled down to fit within MAX_WIDTHxMAX_HEIGHT if larger.

The gravity (g) argument is optional and it can also take the following values:

• n: North
• e: East
• w: West
• s: South

Instead of gravity you can also use a strategy (s) argument:

• a: Attention
• e: Entropy

The format (f) argument is optional as well and selects the output format:

• avif: AVIF (default)
• webp: WebP

Arguments can be given in any order (/f:webp/g:n/ equals /g:n/f:webp/). Each argument may appear only once, and gravity and strategy cannot be combined.

For more details on how crops are applied with these arguments read the Sharp documentation.

Environment variables

• DEBUG: Enable debug logging
• BASE_URL: The base URL of the upstream server
• MAX_WIDTH: The maximum width of the target image (Default: 2000)
• MAX_HEIGHT: The maximum height of the target image (Default: 2000)
• RESIZE_CONCURRENCY: The maximum number of images resized at the same time, which bounds peak memory (Default: 2)
• MAX_INPUT_PIXELS: The maximum number of pixels (width x height) of a source image; larger sources are rejected (Default: 100000000, i.e. 100 megapixels)
• MAX_SIZE: The maximum size of the source image in megabytes (Default: 5)
• REVALIDATE_TIME: The time in minutes for checking the source image for changes after its last access (Default: 30)
• TIMEOUT: The timeout in seconds when fetching source images (Default: 15)
• MAX_REDIRECTS: The maximum number of redirects when fetching source images (Default: 5)
• CACHE_DIR: The directory to store the source and target images in (Default: /home/node/cache)
• CACHE_CONTROL_MAX_AGE: The maximum age of the cache in hours (Default: 1)
• CLUSTER_MODE: Enable cluster-aware routing in Kubernetes (Default: false)