Manual setup

If you would like to manually deploy the managed cloud API within your own cloud infrastructure, you can follow the instructions on this page.

Need help?

Hybiscus can undertake the process of setting up the Managed Cloud API within your cloud infrastructure, if you're using Microsoft Azure.

Get up and running faster in your own cloud using our dedicated service, which you can purchase from the link here. For more details on this service, feel free to reach out to us at support@hybiscus.dev.

To setup this deployment, you will need to run between 1 and 3 containers. The containers required are as follows:

• Hybiscus managed cloud API
• Hybiscus managed cloud worker
• Redis

The two Hybiscus containers use the same image hybiscusdev.azurecr.io/managed-cloud/api:latest. You can replace latest with a specific version (listed here).

To setup the API container, launch the image with port 3000 exposed and providing the following environment variables:

• HYBISCUS_API_KEY – your API key from the Hybiscus dashboard
• API_KEY – the API key used to protect this managed cloud API deployment

If you would like to setup the async API, you will also need to provide the following environment variables:

• ENABLE_ASYNC_API – set to TRUE
• REDIS_HOST – the host of where your Redis service is running. This could be a separate Docker container. Defaults to localhost, if not set. To access Redis from your host O/S, set value to host.docker.internal.
• REDIS_PORT – the port number of your Redis server. Defaults to 6379, if not set.
• REDIS_DB - the name of the Redis database. Defaults to 1 if not set.
• REDIS_PASSWORD - the password for the Redis server. Defaults to null if not set, and ignored.
• REDIS_SSL - whether to enable SSL authentication when connecting to the Redis server (boolean value). Defaults to false if not set.
• REDIS_MTLS - whether to enable mutual TLS authentication when connecting to a Redis server using SSL (boolean value). Defaults to false if not set. If enabled, you must mount the client certificate and key files, as well as the CA certificate file.

If using the async API, you will also need to mount a volume to /usr/app/data where the generated PDF reports will reside. This volume will also need to be mounted in the next container, explained below.

An equivalent Docker CLI command would be:

docker run \
-p 3000:3000 \
-e HYBISCUS_API_KEY=YOUR_API_KEY \
-e API_KEY=CUSTOM_API_KEY \
-e ENABLE_ASYNC_API=TRUE \
-e REDIS_HOST=host.docker.internal \
-e REDIS_PORT=6379 \
-v $(pwd)/data:/usr/app/data \
hybiscusdev.azurecr.io/managed-cloud/api:latest

If you have opted to use the async API, you must also launch another container using the same image (hybiscusdev.azurecr.io/managed-cloud/api:latest), however using the entrypoint override set to ./entrypoint-worker.sh.

You will need to provide ALL the same environment variables as mentioned above, including mounting a volume to /usr/app/data that is the same as above.

An equivalent Docker CLI command would be:

docker run \
-e HYBISCUS_API_KEY=YOUR_API_KEY \
-e API_KEY=CUSTOM_API_KEY \
-e ENABLE_ASYNC_API=TRUE \
-e REDIS_HOST=host.docker.internal \
-e REDIS_PORT=6379 \
-v $(pwd)/data:/usr/app/data \
--entrypoint "./entrypoint-worker.sh" \
hybiscusdev.azurecr.io/managed-cloud/api:latest

The Redis server can be launched either using a Docker container and the official Redis image, a local installation on your server, or using a hosted service. In all scenarios, follow the instructions of your provider to setup the Redis server.

If your Redis server uses SSL, you must launch the containers using REDIS_SSL set to TRUE. To enable mutual TLS, you must also set REDIS_MTLS to TRUE, and provide the below certificate files mounted individually:

• ca.pem - the CA certificates file
• client-cert.pem - the client certificate file
• client-key.pem - the client key file

With these ready, you can use the following command to launch the API:

docker run \
-p 3000:3000 \
-e HYBISCUS_API_KEY=YOUR_API_KEY \
-e API_KEY=CUSTOM_API_KEY \
-e ENABLE_ASYNC_API=TRUE \
-e REDIS_HOST=host.docker.internal \
-e REDIS_PORT=6379 \
-e REDIS_DB=1 \
-e REDIS_PASSWORD=foobarred \
-e REDIS_SSL=TRUE \
-e REDIS_MTLS=TRUE \
-v $(pwd)/data:/usr/app/data \
-v $(pwd)/certs/ca.pem:/usr/app/certs/ca.pem \
-v $(pwd)/certs/client-cert.pem:/usr/app/certs/client-cert.pem \
-v $(pwd)/certs/client-key.pem:/usr/app/certs/client-key.pem \
hybiscusdev.azurecr.io/managed-cloud/api:latest

And finally, the worker can be launched with this commmand:

docker run \
-e HYBISCUS_API_KEY=YOUR_API_KEY \
-e API_KEY=CUSTOM_API_KEY \
-e ENABLE_ASYNC_API=TRUE \
-e REDIS_HOST=host.docker.internal \
-e REDIS_PORT=6379 \
-e REDIS_DB=1 \
-e REDIS_PASSWORD=foobarred \
-e REDIS_SSL=TRUE \
-e REDIS_MTLS=TRUE \
-v $(pwd)/data:/usr/app/data \
-v $(pwd)/certs/ca.pem:/usr/app/certs/ca.pem \
-v $(pwd)/certs/client-cert.pem:/usr/app/certs/client-cert.pem \
-v $(pwd)/certs/client-key.pem:/usr/app/certs/client-key.pem \
--entrypoint "./entrypoint-worker.sh" \
hybiscusdev.azurecr.io/managed-cloud/api:latest

You should now be ready to use your Hybiscus managed cloud API. The API will be accessible on port 3000. If deploying in the cloud, you may also want to use an NGINX container as a reverse proxy to assign a domain name to your deployment, as well as provide HTTPS encryption. Hybiscus recommends Azure Container Apps, as this handles HTTPS connections and reverse proxying out of the box, as well as the ability to scale up the worker containers to handle increased demand.