Deploy your own image processing API using Imaginary on Koyeb

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 Overview tab of the Koyeb control panel and click Create Web Service to begin:

1. Choose Docker as the deployment method.
2. Enter h2non/imaginary as the Docker image.
3. In the Deployment section, click the Override toggle associated with Command args and enter [-enable-url-source, -p, 9000, -http-cache-ttl, 604800] in the field. If you want to restrict image source processing to certain origins, you can modify the argument lists. For example, [-enable-url-source, -p, 9000, -http-cache-ttl, 604800, -allowed-origins, "http://localhost,http://domain.tld.com,http://*.domain.tld"].
4. In the Exposed ports section, change the export port to 9000.
5. Choose a name for your App and Service, for example imaginary-image-processing, and click Deploy.

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.