|
Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Learn how to build your microservices with Paketo Buildpacks and Open Liberty then run them in containers.
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.
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.
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.
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.
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:baseNow, 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-SNAPSHOTReview 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 |
|---|---|
--buildpack |
Buildpack to be included in the OCI build process. |
--env |
Enviornment variables for the |
--docker-host |
Address to docker daemon that will be exposed to build container. Use |
--trust-builder |
Trust the provided builder. |
--creation-time |
Time at which the build was created. Accepts a unix time stamp or |
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 |
|---|---|
BP_JAVA_APP_SERVER |
The application server to use. |
BP_MAVEN_BUILT_ARTIFACT |
Include the |
BP_LIBERTY_PROFILE |
The Liberty profile to use. Defaults to |
Explore all of the flags, variables and options available for the Paketo Liberty buildpack on the Paketo Liberty page.
When building your Open Liberty image with Podman or Docker the structure of the image is similar to the following example:
-
/opt/ol/wlpcontains the Liberty runtime. -
/configcontains 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-kernelcontains the Liberty runtime. -
/layers/paketo-buildpacks_liberty/open-liberty-runtime-kernel/usr/servers/defaultServercontains 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.
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 |
|---|---|
--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: |
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
You can test your system service manually by hitting the endpoint or with automated test that checks your running container.
Create theSystemEndpointITclass.system/src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.java
SystemEndpointIT.java
link:finish/system/src/test/java/it/io/openliberty/guides/system/SystemEndpointIT.java[role=include]The testGetProperties() method checks for a 200 response code from your system service endpoint.
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=9080If 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
podman stop system
docker stop system
You have just built a microservice image with Paketo Buildpacks and ran it in a container.