Building workflow images using Quarkus CLI

This document describes how to build a Serverless Application Container image using the Quarkus CLI.

Prerequisites

A workflow project is created.

For more information about creating a workflow project, see Creating your first Serverless Workflow service.
Latest version of Docker is installed. Alternatively, you can use Jib to build container images. However, Docker is required to build GraalVM native image using the Quarkus native builder image.
Optionally, GraalVM 22.3.0 is installed.

Quarkus provides a few extensions to build container images, such as Jib, docker, s2i, and buildpacks. For more information about the Quarkus extensions, see the Quarkus documentation.

The examples in this document assume that you have the Quarkus tooling installed. For more information about the tooling, see Getting familiar with SonataFlow tooling.

Using an example application

To get started with building workflow images, you can use the serverless-workflow-greeting-quarkus example application.

You can skip the following procedure if you already have a workflow application.

Procedure

Clone the kogito-examples repository and navigate to the serverless-workflow-greeting-quarkus example application.

Clone an example application

git clone --branch main https://github.com/kiegroup/kogito-examples.git
cd kogito-examples/serverless-workflow-examples/serverless-workflow-greeting-quarkus

To run the example application, follow the instructions in Creating your first workflow service.
Install the Quarkus command line interface (CLI). For more information, see Installing the Quarkus CLI.
Add the required Quarkus extension using Quarkus CLI:
Add the Jib extension

The kogito-examples already have this extension added by default, and can be activated with the container Maven profile.

The steps to add the extension in your Serverless Workflow application are:
quarkus extension add 'container-image-jib'
After adding the Jib extension, you can verify the newly added dependency in the pom.xml file:
Verify the Jib extension
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-container-image-jib</artifactId> </dependency>

Building the workflow application

After installing the required tooling, you can start building your workflow application.

Prerequisites

You have created a Quarkus project.
Quarkus CLI is installed. For more information about installing the Quarkus CLI, see Installing the Quarkus CLI.

Procedure

In a command terminal, navigate to your Quarkus project.
To build your workflow application on Quarkus, set the quarkus.container-image.build property value to true and run the following command:
Build your workflow application
quarkus build -Dquarkus.container-image.build=true
The previous command builds your image with name: {system_username}/{project_artifactId}:{project_version}.

Optionally, you can set the following properties to specify the image:
- quarkus.container-image.registry: To define the registry address of the image, such as quay.io. When using OpenShift use the provided registry.
- quarkus.container-image.group: To define the registry namespace of the image. For example, context/namespace or in case of Kubernetes or OpenShift namespace/project.
- quarkus.container-image.name: To override the image name. By default, this property uses artifact ID.
Build your workflow application with specific image information
quarkus build -Dquarkus.container-image.build=true \ -Dquarkus.container-image.group=kogito \ -Dquarkus.container-image.name=serverless-workflow-greeting-quarkus \ -Dquarkus.container-image.tag=1.0 \ -Dquarkus.container-image.registry=quay.io
The added Jib extension caches the target/lib directory. Based on the size of your project, Jib speeds up the rebuilds.
You can also push your workflow application to the defined registry. You need to set the quarkus.container-image.push property value to true (default value is false).
Example of pushing the built workflow application to a registry
```
quarkus build -Dquarkus.container-image.build=true \
    -Dquarkus.container-image.group=kogito \
    -Dquarkus.container-image.name=serverless-workflow-greeting-quarkus \
    -Dquarkus.container-image.tag=1.0 \
    -Dquarkus.container-image.registry=quay.io \
    -Dquarkus.container-image.push=true
```
The previous command results in the following container image pushed to quay.io:

quay.io/kogito/serverless-workflow-greeting-quarkus:1.0

Alternatively, you can create an Apache Maven profile to build the container image, which can be triggered by setting the target profile.

Example Apache Maven profile

<profile>
  <id>build-container</id>
  <properties>
    <quarkus.container-image.build>true</quarkus.container-image.build>
    <quarkus.container-image.group>kogito</quarkus.container-image.group>
    <quarkus.container-image.name>serverless-workflow-greeting-quarkus</quarkus.container-image.name>
    <quarkus.container-image.tag>1.0</quarkus.container-image.tag>
    <quarkus.container-image.registry>quay.io</quarkus.container-image.registry>
    <quarkus.container-image.push>true</quarkus.container-image.push>
  </properties>
</profile>

You can activate the created Apache Maven profile using Quarkus CLI:

Activate the Apache Maven profile

 quarkus build -- -Pbuild-container

Building the workflow application using a native image

When it comes to workflows, a small startup footprint is expected, which can be better when using the native builds to build a workflow application.

Prerequisites

You have created a Quarkus project.
Quarkus CLI is installed. For more information about installing the Quarkus CLI, see Installing the Quarkus CLI.

Procedure

In a command terminal, navigate to your Quarkus project.

To build a native image, pass the --native flag using Quarkus CLI:

Example of building a native image

quarkus build --native -Dquarkus.container-image.build=true \
    -Dquarkus.container-image.group=kogito \
    -Dquarkus.container-image.name=serverless-workflow-greeting-quarkus \
    -Dquarkus.container-image.tag=1.0-native \
    -Dquarkus.container-image.registry=quay.io

The previous command results in the following container image:

quay.io/kogito/serverless-workflow-greeting-quarkus:1.0-native

In case GraalVM is not installed, you can set the -Dquarkus.native.container-build=true system property, which creates a Linux executable.

Configure Docker to use the in-cluster (Remote) Docker daemon

When build Container Images using a remote Docker Daemon, i.e. Minikube, you need to use the following system property instead of -Dquarkus.native.container-build=true

System property to use a remote Docker Daemon

-Dquarkus.native.remote-container-build=true

For more information about native builds, see Building a native executable.

Testing your workflow image

After building your workflow image using Quarkus CLI, you can test the built image.

Prerequisites

Latest version of Docker is installed.

Procedure

Start JVM and native Container Images.

Example JVM image
Example native image

docker run -it -p 8080:8080 quay.io/kogito/serverless-workflow-greeting-quarkus:1.0
...
INFO  [io.quarkus] (main) serverless-workflow-greeting-quarkus 1.22.1.Final on JVM (powered by Quarkus 2.9.2.Final) started in 1.302s

docker run -it -p 8080:8080 quay.io/kogito/serverless-workflow-greeting-quarkus:1.0-native
...
INFO  [io.quarkus] (main) serverless-workflow-greeting-quarkus 1.22.1.Final native (powered by Quarkus 2.9.2.Final) started in 0.039s

Note that the startup of native image is faster than the JVM image.

To invoke the workflow application, execute the following command once the container is started:

Example request
Example response

curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"name": "John", "language": "English"}' http://localhost:8080/jsongreet

{
    "id": "2acf710d-7e4a-481d-925c-dfd85a369987",
    "workflowdata": {
        "name": "John",
        "language": "English",
        "greeting": "Hello from JSON Workflow, "
    }
}

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!