Difficulty: Beginner
Estimated Time: 20 minutes

Cellery is an architectural description language, tooling and extensions for popular cloud-native runtimes that enables agile development teams to easily create a composable enterprise in a technology neutral way. You will be deploying a Hello World using Cellery in this scenario.

Congratulations, You wrote your first cell file and deployed successfully.

Writing cell file from scratch

Step 1 of 2

Writing a cell file

We are configuring a Cellery installation for you. This will take a few minutes to complete.

While it is configuring let's write a simple hello world cell file from scratch.

  1. First, create a new hello-world.bal file to write some code.

  2. We need to import celleryio/cellery package which contains the SDK for writing cells. The ballerina/config is used for reading configurations from the environment variables.

    import ballerina/config;
    import celleryio/cellery;
  3. The build function is the most important function which you build up your cell using SDK. This function is executed when you issue a cellery build command to build a reusable cell image.

    public function build(cellery:ImageName iName) returns error? {
  4. Let's create a new Component which based on a hello world docker image.

        cellery:Component helloComponent = {
  5. Give it a name. Naming your component is always a good idea.

            name: "hello",
  6. Specify the docker image in the source section.

            src: {
                image: "wso2cellery/samples-hello-world-webapp"
  7. The ingress section is the place where you declare how your component get exposed from the cell. As our hello world application is producing html web page, we are going to expose it as a WebIngress. The WebIngress will expose your cell outside from the Kubernetes cluster with hostname specified in vhost section.

            ingresses: {
                webUI: <cellery:WebIngress>{
                    port: 80,
                    gatewayConfig: {
                        vhost: "hello-world.com",
                        context: "/"
  8. This is where you defined the environment variables for your component. Here, we are giving Cellery to HELLO_NAME variable which is used when producing hello world message.

            envVars: {
                HELLO_NAME: { value: "Cellery" }
  9. Make sure to close the curly brackets for the Component

  10. Now you can define a CellImage and attach the components

        cellery:CellImage helloCell = {
            components: {
                helloComp: helloComponent
  11. Call the cellery:createImage to build the actual cell image.

        return <@untainted> cellery:createImage(helloCell, iName);
  12. Close the curly brackets for the build function

  13. The run function is executed when you issue a cellery run command to deploy a cell.

    public function run(cellery:ImageName iName, map<cellery:ImageName> instances, boolean startDependencies, boolean shareDependencies) returns (cellery:InstanceState[]|error?) {
  14. We can use cellery:constructCellImage to generate our original cell image and do various modification before running the cell.

        cellery:CellImage|cellery:Composite helloCell = cellery:constructImage(iName);
  15. We are planing to read the hostname from VHOST_NAME environment variable

        string vhostName = config:getAsString("VHOST_NAME");
        if (vhostName !== "") {
            cellery:WebIngress web = <cellery:WebIngress>helloCell.components["helloComp"]["ingresses"]["webUI"];
            web.gatewayConfig.vhost = vhostName;
  16. Here, we are setting a custom hello message if user specified via environment variable

        string helloName = config:getAsString("HELLO_NAME");
        if (helloName !== "") {
            helloCell.components["helloComp"]["envVars"]["HELLO_NAME"].value = helloName;
  17. Finally, we are creating the actual deployable cell instance by calling cellery:createInstance function.

        return <@untainted> cellery:createInstance(helloCell, iName, instances, startDependencies, shareDependencies);
  18. Close the curly brackets for the run function


Congratulations! You just wrote your first cell file.