Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Cellery Logo

Build Status codecov GitHub (pre-)release GitHub (Pre-)Release Date GitHub last commit License

Build, run, and manage code-first composites on Kubernetes.

In this README:

In addition, here are some other documents you may wish to read:


Cellery is a code-first approach to building, integrating, running and managing composite microservice applications on Kubernetes. Build, push/pull, run, scale and observe composites. Create secure APIs by default, code components in any language.

Why Cellery?

The use of microservices and/or serverless functions is exploding as organisations aim to get better agility and speed of development. This quickly gets out of control, resulting in tens or hundreds of microservices in a highly connected network. There is a strong need for an approach that helps create higher-level constructs from multiple microservices and serverless functions. Cellery aims to create composites with well-defined boundaries that fit with CI/CD pipelines and modern development and DevOps practices. You can read more about this approach here

Cellery intro

Cellery provides a developer tooling, runtime and a management plane. This allows you to develop, run and manage your composite microservice applications on Kubernetes.

  • Cellery SDK

    The SDK allows developers to write, build, run & manage cells. A cell description file is written using the Ballerina programming language. In a nutshell, this file declares the microservice components that have to be included in the cell, the relationship between those components, dependencies to other cells, and it also declares the API that need to be exposed.

    A CLI is also part of this SDK, which allows you to build, run, test and manage your cells.

  • Cellery Mesh

    The mesh provides the wiring & communications medium between cells. Components in a cell cannot invoke components in other cells directly. Only APIs exposed by the cells are invokable. These interactions are strictly governed by security policies.

  • Cellery Management

    This consists of a management plane, which allows you to observe your cells in the runtime, as well as other runtime aspects, and it also allows you to manage security and other policies.

Quickstart Guide

The easiest way to setup Cellery is using the 'local' mode which creates Cellery runtime on Minikube.

Kindly note that if you freshly installed minikube, you would have to execute minikube start, create a temporary cluster and remove it. This is due to a known issue in minikube (kubernetes/minikube#5716).

For other installation approaches including GCP and Docker for Desktop see here


Download Cellery


Download the latest Cellery(.deb) installer and install it using dpkg command as shown below.

dpkg -i cellery-ubuntu-x64-<version>.deb

Mac OS

  • Download latest Cellery(.pkg) installer and install it by following macOS package installation steps.

  • Cellery is avaialbe as a Brew Cask. Run below to install through Brew

    brew cask install cellery

Setup Cellery runtime

Once Cellery has been installed, verify the installation is working by executing cellery version.

In this quickstart guide, we will install a basic local Cellery runtime by running the following command:

  1. Run the local setup command.

    cellery setup create local -y

    This may take a few minutes. If the setup was successful, you should see the following message:

    ✔ Runtime status (Cellery)...OK
  2. Once the setup completes, run the following command to check the status:

    cellery list instances

    You shouldn't see any errors.

Now that we have installed Cellery let's validate that it is running using a simple cell.

Hello world with Cellery

Let's quickly run a sample hello world cell as shown in the diagram below.

Hello world cell

The hello-world-cell contains one component hello. The hello component is defined by a container image which is written in Node.js and it is a simple webapp. In the quick start we will be deploying the hello-world-cell.

Now let's look at the steps required to run this cell.

  1. Execute the cellery run command that will download the hello-world cell from the wso2cellery organization in cellery hub and run the cell.

    $ cellery run wso2cellery/hello-world-cell:latest -n hello-world-cell

    You should see the following output:

    ✔ Connecting to
    ✔ Fetching metadata
    ✔ Pulling image wso2cellery/hello-world-cell:latest
    ✔ Saving new Image to the Local Repository
    Image Digest : sha256:2d5659e5787df7e7ae0f58671c0b9d857b5a19e5fbdb02fccbc98a64016a97f6
    ✔ Extracting Cell Image wso2cellery/hello-world-cell:latest
    ✔ Reading Image wso2cellery/hello-world-cell:latest
    Info: Main Instance: hello-world-cell
    Info: Validating dependencies
    Info: Instances to be Used
    INSTANCE NAME                  CELL IMAGE                          USED INSTANCE             KIND            SHARED
    hello-world-cell               wso2cellery/hello-world-cell:latest To be Created             Cell            -
    Info: Dependency Tree to be Used
    No Dependencies
    ✔ Starting main instance hello-world-cell
    ✔ Successfully deployed cell image: wso2cellery/hello-world-cell:latest
    What's next?
    Execute the following command to list running cells:
      $ cellery list instances

    Please allow a few minutes for completion.

  2. Execute cellery list instances to check the status of your cell.

    $ cellery list instances
             INSTANCE        CELL IMAGE                           STATUS        GATEWAY               COMPONENTS          AGE
     ---------------------- ------------------------------------ -------- -------------------------- ------------ -----------------------
      hello-world            wso2cellery/hello-world-cell:latest   Ready    hello--gateway-service        1          30 minutes 48 seconds
  3. Execute the following command and get the minikube ip address of cellery-local-setup

      minikube ip --profile cellery-local-setup

    Add the following line to the /etc/hosts file.


    Note: The above provided value host entry is for Cellery local setup. If you are using a Cellery on,

    • Existing kubernetes cluster (e.g.: Docker for Mac, Kubeadm, Minikube, etc) - Configure the host entry as explained here.
    • GCP - Configure the host entry as explained /etc/hosts as mentioned here.
  4. Now browse to and you should see the web page.

    Congratulations! You have successfully got your first cell running!

  5. Finally, terminate the cell instance that you started using the cellery terminate command.

    $ cellery terminate hello-world-cell

What's next?

Learn about full lifecycle of cells in Cellery from,