Jlink

This guide describes how to build a custom runtime image for your Helidon application using Helidon’s support for the JDK’s jlink tool.

Introduction

JDK 9 introduced the jlink command that supports assembling a set of modules and their dependencies into a custom runtime image. The helidon-maven-plugin has support for easily creating a custom runtime image for your Helidon application resulting in a smaller, better performing runtime.

In this guide you will learn how to build a custom runtime image locally on your machine, as well as how to build it in a Docker image.

What You Need

For this 10 minute tutorial, you will need the following:

Prerequisite product versions for Helidon 4.4.0-SNAPSHOT

Verify Prerequisites:

java -version
mvn --version
docker --version
kubectl version

Setting JAVA_HOME:

# On Mac
export JAVA_HOME=`/usr/libexec/java_home -v 21`

# On Linux
# Use the appropriate path to your JDK
export JAVA_HOME=/usr/lib/jvm/jdk-21

Verify JDK

As noted in the prerequisites above, Java 21 or newer is required (Java 25 or newer is recommended).

$JAVA_HOME/bin/java --version

Creating a custom runtime image requires that the JDK modules are present as *.jmod files, and some distributions do not provide them by default. Check the jmods directory to ensure they are present:

ls $JAVA_HOME/jmods

Generate the Project

Generate the project using the Helidon MP Quickstart Maven archetype.

mvn -U archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-mp \
    -DarchetypeVersion=4.4.0-SNAPSHOT \
    -DgroupId=io.helidon.examples \
    -DartifactId=helidon-quickstart-mp \
    -Dpackage=io.helidon.examples.quickstart.mp

The archetype generates a Maven project in your current directory (for example, helidon-quickstart-mp). Change into this directory and build.

cd helidon-quickstart-mp
mvn package

At this point you can run the application using the JVM:

java -jar target/helidon-quickstart-mp.jar

In another shell test an endpoint:

curl -X GET http://localhost:8080/greet

The application should respond with {"message":"Hello World!"}

Now stop the running application (by pressing Ctrl+C).

For more information about the Quickstart application and other endpoints it supports see the Helidon MP quickstart Guide.

Building a Custom Runtime Image

You can build a custom runtime image in 2 different ways:

• Locally, on your desktop
• Using Docker

Local Build

Build the custom runtime image using the jlink image profile:

mvn package -Pjlink-image

After the build completes it will report some statistics about the build including the reduction in image size.

The target/helidon-quickstart-mp-jri directory is a self contained custom image of your application. It contains your application, its runtime dependencies and the JDK modules it depends on. You can start your application using the provide start script:

./target/helidon-quickstart-mp-jri/bin/start

Class Data Sharing (CDS) Archive and AOT Cache

If you are building with Java 24 or earlier a Class Data Sharing (CDS) archive is also included in your custom image by default. The CDS archive improves your application’s startup performance and in-memory footprint. You can learn more about Class Data Sharing in the JDK documentation.

If you are building with Java 25 or later an AOT Cache is created instead of a CDS archive. The AOT Cache is more advanced than the CDS archive and over time will contain more optimizations for improving application startup performance. You can learn more about the AOT Cache in the following JEPS: JEP 483, JEP 515, JEP 514

An on-disk cache (CDS Archive or AOT Cache) increases the size of the custom image to get these performance optimizations. It can be of significant size (tens of MB). The size of the on-disk cache is reported at the end of the build output.

If you want to skip the creation of the on-disk cache you can do so by executing your build like this:

For Java 24 or earlier

mvn package -Pjlink-image -Djlink.image.addClassDataSharingArchive=false

For Java 25 or later

mvn package -Pjlink-image -Djlink.image.aotCache=false

For more information on available configuration options see the helidon-maven-plugin documentation.

Multi-Stage Docker Build

To build a Docker image with a custom Java runtime image use the jlink Dockerfile included with the quickstart.

docker build -t helidon-quickstart-mp-jri -f Dockerfile.jlink .

Start the application:

docker run --rm -p 8080:8080 helidon-quickstart-mp-jri:latest

You can exercise the application’s endpoints as before.

Using Custom Runtime Images

Custom runtime images are ideal for use when you want all the runtime performance of the JDK JVM in a reasonably compact form.

For cases where absolute minimal startup time and image size are required, then consider using GraalVM Native Images.