NAME URL *incubator https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml experimental https://github.com/appsody/stacks/releases/latest/download/experimental-index.yaml
- What you’ll learn
- Discovering Appsody repositories and stacks
- Creating an application
- Running an application
- Testing your application
- Debugging your application
- Building your application for deployment
Developing microservice applications with the Appsody CLI
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.
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.
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.
Adding a Kabanero Collection Hub
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
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.
Run the following command:
appsody repo add kabanero https://github.com/kabanero-io/collections/releases/latest/download/kabanero-index.yaml
Check that the repository changes are added successfully by running the
appsody repo listcommand again. The output should be similar to the following example:
NAME URL *incubator https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml experimental https://github.com/appsody/stacks/releases/latest/download/experimental-index.yaml kabanero https://github.com/kabanero-io/collections/releases/latest/download/kabanero-index.yaml
Setting your default repository
appsody repo set-default <repo-name>
You can change the default repository by using the
appsody repo set-default <repo-name> command.
kabaneroCollection Hub as your default repository by running the following command:
appsody repo set-default kabanero
appsody repo listagain to check that
kabanerois now the default repository:
NAME URL *kabanero https://github.com/kabanero-io/collections/releases/latest/download/kabanero-index.yaml incubator https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml experimental https://github.com/appsody/stacks/releases/latest/download/experimental-index.yaml
The asterisk indicates that
kabanerois now the default repository.
Viewing the available stacks
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
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
kabaneroCollection Hub. Each collection includes a version number, one or more templates (an asterisk (*) indicates the default template), and a description.
Creating an application
appsody init <repo-name>/<stack> <template>
An Appsody project gives you a containerized development environment that runs with the technology stack of your choice.
Before you create an Appsody project, create a directory to contain the application:
mkdir my-project cd my-project
Then you can run the
appsody initcommand to set up your project, which downloads the template for your chosen stack. Because you already set
kabaneroas your default repository in the last section, run the following command to create a Kabanero
nodejs-expressproject with the default (
appsody init nodejs-express
When the initialization completes you should see the following output:
... Successfully initialized Appsody project
Running an application
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
Run the application now by typing the
http://localhost:3000to see the output.
NOTE: The URL can be different, depending on the collection, so consult the collection’s documentation.
app.jsso that it outputs something other than "Hello from Appsody!". When you save the file, Appsody picks up the change and automatically updates the container.
http://localhost:3000to see the new message.
Checking the status of your Appsody container
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.
appsody pscommand 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
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
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
/health, are available. In addition, you can define further tests for your application in your project
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
To stop the container running the tests, you can quit by pressing Ctrl-C or running
appsody stop in the terminal.
Debugging your application
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.
appsody debugcommand. The output shows the exposed debug port. For the Kabanero
nodejs-expresscollection, 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 stopin the terminal.
Building your application for deployment
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.
appsody buildcommand. This command completes the following two actions:
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
Runs a Docker build against the
Dockerfilethat 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 buildwith no parameters, the image is given the same name as your project.
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 imagescommand. 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.