Deploy Serverless Docker Containers and Functions with Koyeb CLI
Tags: serverless, docker, cloud, cli
Published: 2020-11-26 09:33:03

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](https://www.koyeb.com/static/images/illustrations/deploy-serverless-docker-containers-and-functions-with-koyeb-cli.svg)

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:

* [Deploy and run Docker containers](#deploy-and-run-docker-containers)
* [Deploy Python and Node.js functions](#deploy-python-and-nodejs-functions)

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

## Getting Started

### Installation

Koyeb CLI is available as [pre-compiled binaries](https://github.com/koyeb/koyeb-cli/releases) 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](https://github.com/koyeb/koyeb-cli) for more details!


### Log in
Once installed, type: `koyeb init` to create the CLI configuration.

```bash
➜ 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](https://app.koyeb.com/account/api).

## 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:

```yaml
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](https://cloudevents.io/) 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: https://api.github.com/repos/koyeb/koyeb-cli/releases/latest
```

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": "https://api.github.com/repos/koyeb/koyeb-cli/releases/34190372",
[..]
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](https://app.koyeb.com/stacks/new) 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](//koyeb.com/docs/stacks/quickstart/deploy-from-github).

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](https://github.com/koyeb/koyeb-cli). 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](https://app.koyeb.com/auth/signup)**

As always, we're available through our [**support channel**](https://app.koyeb.com/support), [**Slack**](https://slack.koyeb.com) or through our integrated instant messaging system if you have a question or want to share feedback.