Deploy Serverless Docker Containers and Functions with Koyeb CLI

November 25, 2020

Édouard Bonlieu

Édouard Bonlieu

Yann Léger

Yann Léger

5 min read

The Koyeb CLI (Command Line Interface) is now available and ready to let you manage all your Koyeb resources directly from your shell! The Koyeb CLI is a critical piece to improve the deployment experience and provide a fast way to interact with Koyeb when you develop your projects.

CLI Demo

As engineers, we spend hours using the terminal, that's why we designed the CLI to be as simple and intuitive as possible. With the CLI, it's easy to automate and perform bulk actions without leaving the terminal. This first release allows you to quickly deploy Docker containers, configure Stacks and Secrets, invoke your functions, monitor your executions, and much more!

In this post, we will check how to use the CLI to:

Let's get started and try some of the cool features!

Getting Started


Koyeb CLI is available as pre-compiled binaries for Linux, macOS and Windows or as a go package. Once installed, the koyeb command will be available directly in your shell. Check out the installation instructions for more details!

Log in

Once installed, type: koyeb init to create the CLI configuration.

➜ koyeb init ? Do you want to create a new configuration file in (/Users/kbot/.koyeb.yaml)? [y/N] Enter your api credential: ****************************************************************█ INFO[0006] Creating new configuration in /Users/kbot/.koyeb.yaml

The CLI will ask for a Koyeb API Token. You can generate one directly from the control panel.

Deploy and run Docker containers

Hello-world container

To deploy Docker containers with the CLI simply create a YAML file with your target configuration. We will start with a simple hello-world function in our configuration:

functions: - name: hello-world image: ubuntu command: ["bash", "-c", "echo 'hello-world from Koyeb'"]

We can now create a new stack called hello-stack with koyeb create stack -n <stack_name> and deploy our configuration with koyeb create revision <stack_name> -f <config.yaml>.

koyeb create stack -n hello-stack koyeb create revision hello-stack -f koyeb.yaml

Your stack is deployed, let's check the status with koyeb get revision <stack_name>:

$ koyeb get revision hello-stack SHA COMMIT INFO MESSAGE STATUS CREATED AT ea7efa270c91548b66308830c48a35415d0d496b ACTIVE 2020-11-24T14:17:18.393Z

If your stack is in the BUILDING state, just wait a few seconds for the deployment to complete.

To invoke the function use koyeb invoke function <stack_name> <function_name>. You can get the logs streamed as it executes with --tail:

$ koyeb invoke function hello-stack hello-world --tail INFO[0000] Event sent: 713cb3ae-11df-499f-8a0b-c5b3d7ffe448 INFO[0006] hello-world from Koyeb INFO[0020] Function exited with state SUCCEEDED

Et voilà! You know how to deploy and invoke functions.

Sending events and parameters with Koyeb CLI

We will deploy a second function called fetch-api which fetches data from an API. The API to scrap will be determined from the event received. To do that, we will use the stedolan/jq Docker image to read the correct field in our JSON event.

Let's modify our koyeb.yaml file as follow:

functions: - name: hello-world image: ubuntu command: ["bash", "-c", "echo 'hello-world from Koyeb'"] - name: fetch-api image: stedolan/jq command: ["bash", "-c"] args: ['wget -q -O - `jq -r .data.url /koyeb/events/in/raw`']

We can now deploy this new version of our stack with koyeb create revision hello-stack -f koyeb.yaml and follow the deployment with koyeb get revision :

$ koyeb get revision hello-stack SHA COMMIT INFO MESSAGE STATUS CREATED AT 8a1e6c7f1c660c91f50cd89a5b69451dbd93fe1b ACTIVE 2020-11-24T14:34:56.371Z ea7efa270c91548b66308830c48a35415d0d496b STOPPING 2020-11-24T14:17:18.393Z

We will now invoke our function with the url to scrap. Koyeb uses the cloudevent specification to define events format. You can use YAML or JSON to write events which will be sent to your function. We will create an event.yaml file and request to fetch the GitHub API with the following content:

type: scrap-request source: cli data: url:

Let's now invoke the function with this event:

✗ koyeb invoke function hello-stack fetch-api --tail -f event.yaml INFO[0000] Event sent: 8a9721c4-0243-4e0a-a40d-6a22f4b23a8b INFO[0002] { INFO[0002] "url": "", [..] INFO[0004] } INFO[0020] Function exited with state SUCCEEDED

You now know how to easily invoke your functions directly from your shell!

Deploy Python and Node.js functions

You can also use the Koyeb CLI to invoke code functions and containers deployed from GitHub.

Instead of using koyeb create stack, you simply need to connect your GitHub repository through the web interface and add a koyeb.yaml file in your repository. The deployment will be automatically done each time you git push. You can read more about the GitHub integration in our documentation.

You can use koyeb get revision and koyeb invoke function in the same way as for other stacks.

Start using Koyeb CLI today!

The Koyeb CLI is written in Go and is completely open-source. Comments, feature requests and contributions are always welcome!

We're happy to provide 1000 hours of compute, 1TB of storage, and 5TB of bandwidth per month for free until the end of the year! Sign up now

As always, we're available through our support channel, our community platform or through our integrated instant messaging system if you have a question or want to share feedback.

Welcome to Koyeb

Koyeb is a developer-friendly serverless platform to deploy any apps globally.

Start for free
Start for free, pay as you grow

Deploy 2 services for free and enjoy our predictable pricing as you grow

Deploy your first app in no time

Get up and running in 5 minutes