Deploy your own image processing API using Imaginary
Tags: tutorial, docker, webdev, serverless
Published: 2021-05-14 09:08:36


## Introduction

[Imaginary](https://github.com/h2non/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](https://www.koyeb.com) 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)

## 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](https://app.koyeb.com) 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](https://github.com/h2non/imaginary#supported-operations-names).