What you’ll learn
Additional prerequisites
Getting started
Packaging your microservices
Building images with Paketo buildpacks
Running your microservices in containers
Testing the microservices
- Running the tests
Great work! You’re done!
Guide Attribution

Building microservices with Paketo Buildpacks

15 minutes

Prerequisites:

Table of contents

Learn how to build your microservices with Paketo Buildpacks and Open Liberty then run them in containers.

What you’ll learn

You will learn to build a microservice image with Paketo Buildpacks. When you use the Pack CLI with the Paketo Buildpacks, the pack build command will inspect, analyze and construct your Open Liberty microservice into an Open Containers Initiative (OCI) image.

Once your microservice image is built, then you are able to deploy it in different environments in a lightweight and portable manner by using a container and your preferred container manager such as Podman or Docker.

The microservice that you’ll be working with is called system. The system miroservice returns the JVM system properties of the running container. This guide demonstrates how a microservice can be built with Paketo buildpacks and run them with your preferred container manager.

Additional prerequisites

Before starting the guide, ensure that you have installed the Pack CLI and a container manager such as Podman or Docker. For installation of the Pack CLI, refer to the offical Pack documentation and for installation of a container manager, refer to Offical Podman Documentation or the official Docker documentation.

Currently, Pack CLI does not officially support building images for Podman on Windows, so you are limited to using Docker exclusively.

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

git clone https://github.com/openliberty/guide-paketo-buildpacks-intro.git
cd guide-paketo-buildpacks-intro

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Before you begin, make sure you have all the necessary prerequisites.

Packaging your microservices

Navigate to the start directory to begin.

You can find the starting Java project in the start directory. This project contains a microservice called system.

To try out the microservice by using Maven, run the following Maven goal to build the system microservice and run it inside Open Liberty:

mvn liberty:run

After you see the following message in the command-line session, your service is ready:

The defaultServer server is ready to run a smarter planet.

To access the system service, which shows the system properties of the running JVM, see http://localhost:9080/system/properties.

After you are finished checking out the system service, stop the Open Liberty server by pressing CTRL+C in the command-line session where you ran the server. Alternatively, you can run the liberty:stop goal in another command-line session:

mvn liberty:stop

To package your microservice, run the mvn package goal to build the application .war files from the start directory so that the .war file is in the target directory.

mvn package

To learn more about RESTful web services and how to build them, see Creating a RESTful web service for details about how to build the system service.

Building images with Paketo buildpacks

Before attempting to build your system image, ensure that you have installed Pack CLI. The Pack CLI tool facilitates the use of buildpacks and provides functionality to build and rebase images with buildpacks.

Paketo Buildpacks is an open source project which provides users with production-ready buildpacks for the most popular languages and frameworks, including the Open Liberty server. A buildpack is a set of executables that inspects and transforms your application source code into OCI images that can be ran in nearly any container manager.

When a buildpack is executed, there are two phases that occur, the detect phase and the build phase. The detect phase checks against your application source code to ensure the buildpack is applicable. If applicable, the build phase will run which downloads all of the application dependencies, compile your source code and constructs a container image for your application.

The benefits of using Paketo Buildpacks with the Pack CLI to build your application compared to other traditional build tools, include:

Generating your application images without a Containerfile or Dockerfile.
Advanced image cacheing for faster rebuild times of your application.
Generate a software bill-of-materials (SBOM) which provides information on the contents of your final image.
Optimizing image size for minimal final application image.
Auto-detection and installation of your app’s dependencies directly from it’s source code.
Patching OS-level vulnerabilites in your images automatically upon rebuilding.

Setting your default builder

A builder in the buildpack ecosystem, is an image comprised of three parts:

A set of buildpacks that apply your application’s dependencies.
A stack, which provides the OS layer for your appliation image.
A lifecycle which analyzes, detects and assembles your final application image.

The default builder is the builder used by all other commands that are run with the Pack CLI, in this instance, you will set the default builder to the Paketo Buildpacks builder to use the features it offers.

Set your pack default builder to the Paketo Buildpacks builder with the following command:

pack config default-builder gcr.io/paketo-buildpacks/builder:base

Building the image

Now, to begin constructing your system service image, run the following pack build command with the applicable flags and environment variables to customize your Open Liberty image:

PODMAN

DOCKER

pack build --env BP_JAVA_APP_SERVER=liberty --env BP_MAVEN_BUILT_ARTIFACT="target/*.[ejw]ar src/main/liberty/config/*" --env BP_LIBERTY_PROFILE=jakartaee9 --buildpack paketo-buildpacks/eclipse-openj9 --buildpack paketo-buildpacks/java --creation-time now system:1.0-SNAPSHOT

pack build --env BP_JAVA_APP_SERVER=liberty --env BP_MAVEN_BUILT_ARTIFACT="target/*.[ejw]ar src/main/liberty/config/*" --env BP_LIBERTY_PROFILE=jakartaee9 --buildpack paketo-buildpacks/eclipse-openj9 --buildpack paketo-buildpacks/java --docker-host=inherit --trust-builder=true --creation-time now system:1.0-SNAPSHOT

If you would like to try building your images for Podman but have your Pack CLI configured for Docker, then refer to the Build with Podman page in the Pack CLI documentation.

After running your pack build command, the following output verifies that your system image can now be ran in a container:

Successfully built image system:1.0-SNAPSHOT

Review the tables below to better understand the anatomy of the pack build command used to construct your images.

The following table describes the flags supplied to customize your Open Liberty image:

Flag Description

Flag	Description
--buildpack	Buildpack to be included in the OCI build process.
--env	Enviornment variables for the `pack build` process.
--docker-host	Address to docker daemon that will be exposed to build container. Use `inherit` value when the docker daemon address is set to the DOCKER_HOST environment variable.
--trust-builder	Trust the provided builder.
--creation-time	Time at which the build was created. Accepts a unix time stamp or `now` as values.

--buildpack

Buildpack to be included in the OCI build process.

--env

Enviornment variables for the pack build process.

--docker-host

Address to docker daemon that will be exposed to build container. Use inherit value when the docker daemon address is set to the DOCKER_HOST environment variable.

--trust-builder

Trust the provided builder.

--creation-time

Time at which the build was created. Accepts a unix time stamp or now as values.

For more information on all supported flags, view the pack build command documentation.

The following table describes the environment variables supplied for your application image.

Enviornment Variables Description

Enviornment Variables	Description
BP_JAVA_APP_SERVER	The application server to use.
BP_MAVEN_BUILT_ARTIFACT	Include the `server.xml` and the `.war` file from the Maven process into the `pack build` process.
BP_LIBERTY_PROFILE	The Liberty profile to use. Defaults to `full`.

BP_JAVA_APP_SERVER

The application server to use.

BP_MAVEN_BUILT_ARTIFACT

Include the server.xml and the .war file from the Maven process into the pack build process.

BP_LIBERTY_PROFILE

The Liberty profile to use. Defaults to full.

Explore all of the flags, variables and options available for the Paketo Liberty buildpack on the Paketo Liberty page.

Understanding the image structure

When building your Open Liberty image with Podman or Docker the structure of the image is similar to the following example:

/opt/ol/wlp contains the Liberty runtime.
/config contains the server configuration.

This structure is expected if you are familiar with building Open Liberty images. Although, when using Paketo Buildpacks, the image takes a different structure. An example of the Paketo Buildpacks structure is as follows:

/layers/paketo-buildpacks_liberty/open-liberty-runtime-kernel contains the Liberty runtime.
/layers/paketo-buildpacks_liberty/open-liberty-runtime-kernel/usr/servers/defaultServer contains the server configuration.

Notice how all of the files have been placed under the /layers directory. This is because Buildpacks do not run as root, so the cnb user/group is created and uses the /layers directory as the location that Buildpacks are able to write to.

To find out more information on the structure of your image, refer to the Buildpack Interface Specification page. Otherwise, continue with the guide to run your system image.

Running your microservices in containers

Now that your system image is built, you will now run it in a container. Since the final image generated from Pack CLI is an Open Containers Initiative (OCI) image, it is compatible with whichever container manager you have configured with Pack CLI.

Execute the following command based on your current container manager to run your newly built image:

PODMAN

DOCKER

podman run --rm -d --name system -p 9080:9080 system:1.0-SNAPSHOT

docker run --rm -d --name system -p 9080:9080 system:1.0-SNAPSHOT

Review the following table that describes the flags in the above command:

Flag Description

Flag	Description
--rm	Removes the container when the container is stopped.
-d	Runs the container in the background.
--name	Specifies a name for the container.
-p	Maps the host ports to the container ports. For example: `-p <HOST_PORT>:<CONTAINER_PORT>`

--rm

Removes the container when the container is stopped.

-d

Runs the container in the background.

--name

Specifies a name for the container.

-p

Maps the host ports to the container ports. For example: -p <HOST_PORT>:<CONTAINER_PORT>

Next, run the following command to verify that your container has been started:

PODMAN

DOCKER

podman ps

docker ps

Make sure that your containers are running and show Up as their status:

CONTAINER ID    IMAGE                   COMMAND                  CREATED          STATUS          PORTS                                        NAMES
99a98313705f    system:1.0-SNAPSHOT     "/opt/ol/helpers/run…"   3 seconds ago    Up 2 seconds    0.0.0.0:9080->9080/tcp, 9443/tcp             system

If a problem occurs and your container exits prematurely, the container won’t appear in the container list that the docker ps command displays. Instead, your container will appear with an Exited status when they run the docker ps -a command. Run the docker logs system command to view the container logs for any potential problems. Run the docker stats system commands to display a live stream of usage statistics for your container. When you find the cause of the issues, remove the faulty container with the docker rm system command. Rebuild your image, and start the container again.

If a problem occurs and your container exits prematurely, the container won’t appear in the container list that the podman ps command displays. Instead, your container will appear with an Exited status when they run the podman ps -a command. Run the podman logs system command to view the container logs for any potential problems. Run the podman stats system command to display a live stream of usage statistics for your container. When you find the cause of the issues, remove the faulty container with the podman stop system command. Rebuild your image, and start the container again.

To access the system service, which shows the system properties of the running JVM, see http://localhost:9080/system/properties

Testing the microservices

You can test your system service manually by hitting the endpoint or with automated test that checks your running container.

Create the SystemEndpointIT class.
system/src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.java

SystemEndpointIT.java

1Unresolved directive in README.adoc - include::finish/system/src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.java[]

The testGetProperties() method checks for a 200 response code from your system service endpoint.

Running the tests

Begin with getting the IP address of your system container by running the following command:

PODMAN

DOCKER

podman inspect system -f "{{ .NetworkSettings.IPAddress }}"

docker inspect system -f "{{ .NetworkSettings.IPAddress }}"

Next, run the Maven package goal to compile the test classes.

Run the Maven failsafe goal to test your system service by replacing the [system-ip-address] with the IP address that you determined previously.

mvn package
mvn failsafe:integration-test -Dsystem.ip=[system-ip-address]  -Dsystem.http.port=9080

If the test passes, you see output similar to the following example:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.system.SystemEndpointIT
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.653 s - in it.io.openliberty.guides.system.SystemEndpointIT

Results:

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

When you are finished with your system service, run the following command to stop and remove your container:

PODMAN

DOCKER