Deploy your own image processing API using Imaginary

Introduction

Imaginary is a fast HTTP microservice written in Go allowing high-level image processing. Behind the scene, imaginary uses bimg and libvips libraries to perform the image manipulations.

In this guide, we will deploy the Imaginary microservice on the Koyeb serverless platform using the Imaginary official Docker image, explore important options to properly deploy the application such as: caching configuration and restrict image source processing from certain origins, and perform a quick tour of the API.

Requirements

To successfully follow and complete this guide, you need:

• A Koyeb account to deploy and run the Imaginary microservice

Steps

To deploy and start using Imaginary to process images, you need to follow these steps:

1. Deploy Imaginary on Koyeb

Deploy Imaginary on Koyeb

Let's get started by deploying the Imaginary Docker image on Koyeb.

Koyeb allows you to deploy Docker images hosted on public or private registries and to override the commands and args if required.

In this guide, we will use the Imaginary official image h2non/imaginary and launch it with additional options to:

• Configure the duration our images need to be cached
• Enable the -enable-url-source flag to allow remove url image source processing via https://<IMAGINARY_API>?url=<REMOTE_IMAGE_URL>
• Restrict image source processing to certain origins (optional)

To deploy Imaginary on Koyeb, go to the Control Panel and click the Create App button.
You land on the App creation form.

In the Docker section, fill the Docker image field with h2non/imaginary and the Args field with our options format as below:

[-enable-url-source, -p, 9000, -http-cache-ttl, 604800]

Or if you want to restrict image source processing to certain origins

[-enable-url-source, -p, 9000, -http-cache-ttl, 604800, -allowed-origins, "http://localhost,http://domain.tld.com,http://*.domain.tld"]

In the Ports section, change the export port from 80 to 9000, which is the port our Imaginary app is listening on. This setting is required to let Koyeb know which port your application is listening to and properly route incoming HTTP requests. We don't need to change the Path, the Imaginary will be available at the root of our domain: /.

Give your App a name, i.e imaginary-image-processing, and click Create App

You can add more regions to deploy your applications, set environment variables, and define the horizontal scaling according to your needs.

The Imaginary container is being deployed on Koyeb and will be accessible using your App URL of form: <APP_NAME>.<ORG_NAME>.koyeb.app.

Let's check everything as excepted running the Imaginary image resize operation:

<APP_NAME>.<ORG_NAME>.koyeb.app/resize?width=500&url=https://raw.githubusercontent.com/h2non/imaginary/master/testdata/large.jpg

Conclusion

In this guide, we saw how easy it is to deploy and run Imaginary on Koyeb and the benefit of Koyeb native features such as native TLS encryption, autoscaling, and more with no effort.

The image processing stack we deployed allows us to process our images faster thanks to the Koyeb 55 edge locations and reduce the number of requests back to origin thanks to the cache TTL configuration we applied to our Imaginary app.

You can discover the complete list of operation Imaginary offers on their GitHub repository.