
## 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 **Overview** tab of the [Koyeb control panel](https://app.koyeb.com) 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](https://github.com/h2non/imaginary#supported-operations-names).


This guide showcases how to configure and deploy imaginary on Koyeb to perform image processing on a global scale.

Imaginary

Deploy your own image processing API using Imaginary on Koyeb