Microservice package and deploy


Cumulocity provides you with an utility tool for easy microservice packaging, deployment and subscription. The script requires a local installation of Docker and jq, which is a lightweight and flexible JSON processor.



Verify that you have a Docker installation. The Docker version must be >= 1.2.6

$ docker version
 Version:         1.12.6
 API version:     1.24
 OS/Arch:         linux/amd64

 Version:         1.12.6
 API version:     1.24
 OS/Arch:         linux/amd64

JSON processor

Execute the following command to install the JSON processor on Linux systems:

$ sudo yum install jq

For macOS, use the following command:

$ brew install jq

Info: You don't need to run Homebrew using sudo as it is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation, you would be giving all build scripts full access to your system.


The microservice utility tool (script) needs version 4+ to run. Verify your Bash version with the following command:

$ bash --version

GNU bash, version 5.0.3(1)-release (x86_64-apple-darwin18.2.0)
Copyright (C) 2019 Free Software Foundation, Inc.

macOS systems come with a preinstalled Bash version 3.x. Hence, you must update it in order to execute the microservice script. To do so, execute the following commands:

$ brew install bash
$ chsh -s /usr/local/bin/bash

If your Bash version has not changed while executing bash --version, you may need to restart your system. Note that the updated interpreter gets installed at /usr/local/bin/bash and you will have to modify the first line of the microservice script as follows:




Configure the microservice utility tool

Execute the following command to download the script on Linux systems:

$ wget http://resources.cumulocity.com/examples/microservice

For macOS, use the following command:

$ curl -O http://resources.cumulocity.com/examples/microservice

Change the mode to allow the script to be executed:

$ chmod +x microservice

Use the help option to see all the available functions (goals) and options:

$ ./microservice help


The following directory structure is required to pack a microservice:

/docker/Dockerfile      # Instructions to build the Docker image
/docker/*               # All files within the directory will be included in the Docker build
/cumulocity.json        # The application manifest

The script can be run in a parent folder holding such structure, or by passing the path to the directory using the -dir option. For instance, to pack a Hello World microservice application, execute:

$ ./microservice pack --name hello-world

It will create a ZIP file named hello-world.zip, and an intermediate image.tar which is an exported Docker image.


Deploying your microservice application is rather easy, just execute the following command:

$ ./microservice deploy -n hello-world -d <URL> -u <username> -p <password> -te <tenant>

Note that you need to have a tenant and user credentials in order to deploy your microservice.
The successful execution will create an application on the Cumulucity platform with the specified name, if it does not exist yet. Then it will upload the hello-world.zip file into the platform. Once it has been uploaded, your application will be listed on Applications > Own Applications in the Administration application.


Execute the following command to subscribe your tenant to the uploaded microservice:

$ ./microservice subscribe -n hello-world -d <URL> -u <username> -p <password> -te <tenant> -id <APPLICATION_ID>

It will result in tenant subscription to an application specified by the ID parameter. If the user has already been subscribed, a warning message will be displayed.

Multiple goals

Goals can be executed together to pack, deploy and subscribe the application in a single line. In this case, the application ID will be automatically pulled by the script.

$ ./microservice pack deploy subscribe -n hello-world -d <URL> -u <username> -p <password> -te <tenant>