Check out what's in the latest release of Kabanero Learn More

Developing microservice applications with the Appsody CLI

duration 20 minutes

What you’ll learn

You will learn how to use the Appsody Command Line Interface (CLI) to configure your local development environment to access a Kabanero Collection. You will then learn how to use the CLI to create, run, test, and debug an application built from a Kabanero Collection. Finally, you will learn how to build a deployment image that is ready to run in a Kubernetes or Knative environment.


  1. Docker must be installed.

  2. Appsody must be installed.

Discovering Appsody repositories and stacks

Kabanero contains Appsody, which is designed to enable applications to be built and tested inside a Docker container. When built, the Docker container can be deployed by Kabanero into a target host environment.

CLI command: appsody repo list

When you install Appsody, the default configuration references a public repository appsodyhub, in which you can see the available Appsody stacks. You can use the content in the public repository, but those stacks are not integrated with Kabanero. In order to use Appsody with Kabanero you need to configure Appsody to use your Kabanero Collection Hub. This repository might be one that you create, based on your own requirements. Alternatively, the repository might be a preconfigured Kabanero Collection that someone in your organization, such as an enterprise architect, has created for you. In either case the Collection Hub must be active in the Kabanero instance on which you wish to deploy your application, and it must be added to Appsody before you create your application.

To see the list of configured Appsody repositories, run the appsody repo list command. The asterisk shown in the output indicates the default repository.

NAME            URL

Adding a Kabanero Collection Hub

CLI command: appsody repo add <repo-name> <URL>

As a developer your enterprise architect might provide you with the URL of a Collection Hub that your organization has defined for developers to use. A Collection Hub is defined by an index.yaml file, which lists all the collections that are available.

To add a Collection Hub, use the appsody repo add <repo-name> <URL> command, supplying a name for the repository and the URL for the Collection Hub. The URL must point to the Collection Hub’s index.yaml file.

In this example, you will add the latest public Kabanero Collection Hub repository instead of a clone of the Kabanero Collection Hub repository that might be customised for your organization.

NOTE: The public Kabanero Collection Hub is updated on a regular basis. By making a copy of the public hub you avoid adopting unplanned changes.

  1. Run the following command:

    appsody repo add kabanero
  2. Check that the repository changes are added successfully by running the appsody repo list command again. The output should be similar to the following example:

    NAME          URL

Setting your default repository

CLI command: appsody repo set-default <repo-name>

You can change the default repository by using the appsody repo set-default <repo-name> command.

  1. Set the kabanero Collection Hub as your default repository by running the following command:

    appsody repo set-default kabanero
  2. Run appsody repo list again to check that kabanero is now the default repository:

    NAME            URL

    The asterisk indicates that kabanero is now the default repository.

Viewing the available stacks

CLI command: appsody list <repo-name>

Now that you have set up your repositories you can view the available stacks with the appsody list command. To limit the output to only one repository, specify the repository name. Run the following command to limit the list of available stacks to the kabanero repository:

  1. Run the appsody list command:

    appsody list kabanero

    The output is similar to the following example, which provides detailed information for each stack:

    REPO          ID                       VERSION    TEMPLATES           DESCRIPTION
    kabanero      java-microprofile        0.2.11     *default            Eclipse MicroProfile on Open Liberty & OpenJ9 using Maven
    kabanero      java-spring-boot2        0.3.9      *default, kotlin    Spring Boot using OpenJ9 and Maven
    kabanero      nodejs                   0.2.5      *simple             Runtime for Node.js applications
    kabanero      nodejs-express           0.2.5      *simple, scaffold   Express web framework for Node.js
    kabanero      nodejs-loopback          0.1.4      *scaffold           LoopBack 4 API Framework for Node.js

    In the output you can see multiple collections (IDs) in the kabanero Collection Hub. Each collection includes a version number, one or more templates (an asterisk (*) indicates the default template), and a description.

Creating an application

CLI command: appsody init <repo-name>/<stack> <template>

An Appsody project gives you a containerized development environment that runs with the technology stack of your choice.

  1. Before you create an Appsody project, create a directory to contain the application:

    mkdir my-project
    cd my-project
  2. Then you can run the appsody init command to set up your project, which downloads the template for your chosen stack. Because you already set kabanero as your default repository in the last section, run the following command to create a Kabanero nodejs-express project with the default (simple) template:

    appsody init nodejs-express

    When the initialization completes you should see the following output:

    Successfully initialized Appsody project

Running an application

CLI command: appsody run

This command runs an Appsody project in a Docker container, where the container is linked to the project source code on the local system. In the previous step, you initialized the nodejs-express collection, which created a project directory that contains a sample app.js application.

  1. Run the application now by typing the appsody run command.

  2. Navigate to http://localhost:3000 to see the output.

    • NOTE: The URL can be different, depending on the collection, so consult the collection’s documentation.

  3. Edit app.js so that it outputs something other than "Hello from Appsody!". When you save the file, Appsody picks up the change and automatically updates the container.

  4. Refresh http://localhost:3000 to see the new message.

Checking the status of your Appsody container

CLI command: appsody ps

To list all the collection-based containers that are running in your local Docker environment, use the appsody ps command. The output provides information about the container ID, name, image, and the status of each container.

  1. Run the appsody ps command to see output that is similar to the following example:

    CONTAINER ID	NAME            IMAGE                     	STATUS
    f20ec098a612	my-project-dev	appsody/nodejs-express:0.2	Up 8 minutes

Stopping your Appsody container

CLI command: appsody stop --name <container-name>

To stop a container you can either, press Ctrl-C in the terminal or use the appsody stop command, which stops the container that is running in your current working directory.

If you have more than one development project open, use the appsody stop --name <container-name> to stop a specific container. Use the appsody ps command to find the name of the container you want to stop.

Testing your application

CLI command: appsody test

The appsody test command runs the test suite for your application in the Appsody development container. Each Kabanero collection provides a set of generic tests, which verify that the capabilities provided by the collection are working as expected. Typically, these tests check that the endpoints that are created, such as /metrics and /health, are available. In addition, you can define further tests for your application in your project /test folder.

In earlier sections of this guide you created a Kabanero nodejs-express project with the default (simple) template, which provides a sample test as a starting point. Take a look at the sample test in the my-project/test/test.js file. You can update this file to suit your test requirements.

Now try running the appsody test command for your project. The results from the test suite are included in the output.

The testing uses constructs that are familiar to the programming language or framework on which the collection is based. You can add your own tests or switch to your preferred testing framework. Node.js collections use the Mocha test framework as default. If you want to use a different test framework, update the npm test command in your project package.json file.

To stop the container running the tests, you can quit by pressing Ctrl-C or running appsody stop in the terminal.

Debugging your application

CLI command: appsody debug

The appsody debug command starts the Appsody development container with a debugger enabled. Typically, your IDE can connect to the debug port used by a Kabanero Collection. You can then set breakpoints and step through your code as it runs in the container.

  1. Run the appsody debug command. The output shows the exposed debug port. For the Kabanero nodejs-express collection, the debug port is 9229.

    • NOTE: The debug port varies, depending on your Kabanero Collection, so check the documentation.

    • To stop the container running in debug mode, you can quit by pressing Ctrl-C or running appsody stop in the terminal.

Building your application for deployment

CLI command: appsody build

The appsody build command generates a Docker image for deployment. This Docker image differs slightly from the development Docker image that is generated by the Appsody CLI for running, testing, and debugging your application.

  1. Run the appsody build command. This command completes the following two actions:

    1. Extracts your code and other artifacts, including a new Dockerfile, which are required to build the deployment image from the development image. These files are saved to the ~/.appsody/extract directory.

    2. Runs a Docker build against the Dockerfile that was extracted in the previous step to produce a deployment image in your local Docker registry. If you want to give your Docker image a name, specify the -t <tag> parameter, for example appsody build -t my-own-project. If you run appsody build with no parameters, the image is given the same name as your project.

  2. Now create a deployment Docker image called my-first-kabanero-app for your application by running the following command:

    appsody build -t my-first-kabanero-app

    NOTE: If your project name includes uppercase characters, these are converted to lowercase characters in the image name because Docker does not accept uppercase characters in image tags. Also, if your project directory includes underscore characters, these are converted to dashes (-), because certain areas of Kubernetes are not tolerant of underscore characters.

    When Appsody finishes the build, check that your image is available by running the docker images command. You should see your image at the top of the list, in a similar format to the following output:

    REPOSITORY                                                                TAG                           IMAGE ID            CREATED             SIZE
    my-first-kabanero-app                                                     latest                        1a957433be51        4 seconds ago       945MB

    Your deployment Docker image can now be used to run your containerized application in a Kubernetes or Knative environment.

Copied to clipboard
Copy code block

Way to go! What's next?

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Where to next?