ideaplexus/imaginary repository overview

⁠imaginary

Fast HTTP microservice for image processing with libvips⁠, a maintained fork of h2non/imaginary⁠. It resizes, crops, rotates, converts and watermarks images, reads JPEG, PNG, WebP, AVIF, HEIF, JPEG XL, GIF, TIFF, SVG and PDF, and writes all of them apart from SVG and PDF.

The source, the full documentation and the issues are on GitLab⁠.

⁠Tags

Every image is built for linux/amd64 and linux/arm64, and mirrored with the same tags to quay.io/ideaplexus/imaginary⁠, e.g. for hosts which reach the pull rate limit of Docker Hub.

latest follows the main branch, <version> is a release, e.g. 2.3.0; see the changelog⁠ and the releases⁠.

⁠Quick start

docker run -p 9000:9000 ideaplexus/imaginary:latest -enable-url-source
curl -o thumb.jpg "http://localhost:9000/resize?width=300&url=https://example.com/photo.jpg"

Images can be posted as well:

curl -o thumb.webp --data-binary @photo.jpg "http://localhost:9000/fit?width=300&height=300&type=webp"

The container listens on port 9000 (PORT) and runs as the user 65534. Options are passed as arguments, or as environment variables IMAGINARY_<OPTION>, e.g. IMAGINARY_ENABLE_URL_SOURCE=true:

services:
  imaginary:
    image: ideaplexus/imaginary:latest
    restart: always
    command: -enable-url-source -max-allowed-size 104857600
    ports:
      - "9000:9000"

Frequently used options:

• -key <secret> requires an API key in the API-Key header or the key param
• -enable-url-source and -allowed-origins fetch remote images, only from these origins
• -mount <dir> serves images of a local directory with the file param
• -max-allowed-size and -max-allowed-resolution limit the size and the resolution of the images
• -log-format json logs in JSON, -enable-metrics serves Prometheus metrics at /metrics

⁠Documentation

• README⁠: the endpoints, their params and all options
• FAQ⁠: fit or resize, padding, crop or extract, watermarks, logs
• Security policy⁠: how to report vulnerabilities

⁠License

MIT, see LICENSE⁠. The images contain libvips and its libraries under their own licenses, e.g. LGPL.