WSO2 unveiled its latest contribution to the world of integration, Ballerina, yesterday during the WSO2Con 2017 in San Fransisco. Ballerina is a general purpose language with a focus on integration and a visual approach to coding. It’s strongly typed, integration friendly, and carries native support for a list of technologies such as support for REST, JSON, XML, Swagger, and “Connectors” that communicate with Facebook, and Twitter etc. This write up will focus on Docker based Containerization of Ballerina programs.

Ballerina offers two downloads, a minimal Runtime, and a fully featured Tools distribution. The Tools distribution packs a list of developer tools required to build Ballerina programs, in addition to the Runtime itself.

Ballerina Composer
  1. Ballerina Composer, a visual Editor through which Ballerina can be coded as Sequence Diagrams
  2. Docerina to generate API documentation
  3. Testerina, a test framework for Ballerina
  4. Helper tools — Swagger-Ballerina Code generator, and Container Support

What we are interested here is the Container Support. Ballerina Container Support enables you to pack Ballerina packages as Docker images that can be used to run individual Ballerina Containers or Ballerina Container Clusters. Let’s follow a simple example.


Ballerina Docker images depend on a common base image, ballerina-pkg:latest. Currently, this has to be manually built.

  1. Download Ballerina Runtime distribution.
  2. Clone Ballerina Container Support repository and checkout tag v0.8.0.
  3. Navigate to ballerina-base-image folder and execute as follows.
./ -d ~/Downloads/ 

After the build process is done, there will be a ballerina-pkg:latest Docker image on the local registry.

ballerina-pkg latest 2547078bf268 13 hours ago 138 MB


Let’s create a Docker image for a sample Ballerina Service.


For Ballerina programs to be packed in to Docker images, they have to be packaged first using ballerina build command.

  1. Download Ballerina Tools distribution and unzip to your development location.
  2. Execute the following build command to package the Ballerina sample helloWorldService as an executable archive.
ballerina-tools-0.8.0/bin/> ./ballerina build service ../samples/helloWorldService/helloWorldService.bal
  1. This will create a Ballerina Service Archive with .bsz file extension at your working directory.


Now let’s create a Docker image out of this Service archive.

  1. Once again, make sure you have ballerina-pkg:latest Docker image in your local registry by executing a docker images command. Note that non-sudo access to the docker command is required forballerina dockerto correctly function.
  2. Execute the following command to create the Docker image.
ballerina-tools-0.8.0/bin/> ./ballerina docker helloWorldService.bsz

This will prompt for you to continue building the Docker image, and confirmed it will build the Docker image and show helpful text to continue the next steps.

Test the Docker image by running a Container. Copy the command displayed to run the Container, which will do so in the background. Query for Container logs to see if the Ballerina Service was successfully deployed, and verify by making an HTTP call.


You have now completed Dockerizing a Ballerina Service.

Dockerizing a Ballerina Main program is just as easy. Just package the Main program to a bmz archive and issue the same command ballerina docker to create a Docker image.

You might have noticed that ballerina docker tagged the Docker images with the package name of the Ballerina Service/Main Archive provided. If you want to tag the resulting Docker image with a different name, you can use -tor --tag flag.

Another feature that ballerina docker offers is to use an external Docker daemon as the Docker host for Docker commands to be executed. This enables resource sharing as a common server with a Docker daemon exposed via a TCP port can be used by a team to create and test Docker images before pushing to live. To specify an external Docker daemon, use the flags -H or --host.

You can find more information on the usage on the README.

Written on February 21, 2017 by chamila de alwis.

Originally published on Medium