Assembling a custom runtime image with jlink

This document will show you how to assemble a custom runtime image with jlink and Maven.

What you need

• A text editor or an IDE

• Java 11 or higher

Create a project

Here is the content of the pom.xml file you should be using:

Maven POM file

Implementing the application

The server setup code fits into a single class, io.vertx.howtos.jlink.ServerVerticle:

ServerVerticle.java

A custom application launcher takes care of deploying the main verticle:

CustomLauncher.java

Having the verticle instance supplied programmatically in io.vertx.howtos.jlink.CustomLauncher simplifies the Java module configuration:

module-info.java

Indeed, we don’t have to export our application package to the io.vertx.core module, we just have to declare a few required modules.

Building the application

On Linux or other Unix-like systems, run the following command:

./mvnw clean package

On Microsof Windows:

mvnw.cmd clean package

Notice that all required modules are resolved before jlink creates the custom runtime image.

[INFO] --- jlink:3.2.0:jlink (jlink) @ jlink-howto ---
[INFO]  -> module: io.netty.handler ( /path/to/my/mavenrepo/io/netty/netty-handler/4.2.0.RC1/netty-handler-4.2.0.RC1.jar )
[INFO]  -> module: io.vertx.web ( /path/to/my/mavenrepo/io/vertx/vertx-web/5.0.0.CR4/vertx-web-5.0.0.CR4.jar )
[INFO]  -> module: io.vertx.core ( /path/to/my/mavenrepo/io/vertx/vertx-core/5.0.0.CR4/vertx-core-5.0.0.CR4.jar )
[INFO]  -> module: io.netty.handler.proxy ( /path/to/my/mavenrepo/io/netty/netty-handler-proxy/4.2.0.RC1/netty-handler-proxy-4.2.0.RC1.jar )
[INFO]  -> module: com.fasterxml.jackson.core ( /path/to/my/mavenrepo/com/fasterxml/jackson/core/jackson-core/2.16.1/jackson-core-2.16.1.jar )
[INFO]  -> module: io.netty.codec.unused ( /path/to/my/mavenrepo/io/netty/netty-codec/4.2.0.RC1/netty-codec-4.2.0.RC1.jar )
[INFO]  -> module: io.vertx.launcher.application ( /path/to/my/mavenrepo/io/vertx/vertx-launcher-application/5.0.0.CR4/vertx-launcher-application-5.0.0.CR4.jar )
[INFO]  -> module: io.vertx.auth.common ( /path/to/my/mavenrepo/io/vertx/vertx-auth-common/5.0.0.CR4/vertx-auth-common-5.0.0.CR4.jar )
[INFO]  -> module: info.picocli ( /path/to/my/mavenrepo/info/picocli/picocli/4.7.4/picocli-4.7.4.jar )
[INFO]  -> module: io.vertx.howtos.jlink ( /path/to/my/Projects/vertx-howtos/jlink-howto/target/classes )
[INFO]  -> module: io.netty.transport.unix.common ( /path/to/my/mavenrepo/io/netty/netty-transport-native-unix-common/4.2.0.RC1/netty-transport-native-unix-common-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.codec.compression ( /path/to/my/mavenrepo/io/netty/netty-codec-compression/4.2.0.RC1/netty-codec-compression-4.2.0.RC1.jar )
[INFO]  -> module: io.vertx.web.common ( /path/to/my/mavenrepo/io/vertx/vertx-web-common/5.0.0.CR4/vertx-web-common-5.0.0.CR4.jar )
[INFO]  -> module: io.netty.buffer ( /path/to/my/mavenrepo/io/netty/netty-buffer/4.2.0.RC1/netty-buffer-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.codec.http2 ( /path/to/my/mavenrepo/io/netty/netty-codec-http2/4.2.0.RC1/netty-codec-http2-4.2.0.RC1.jar )
[INFO]  -> module: io.vertx.core.logging ( /path/to/my/mavenrepo/io/vertx/vertx-core-logging/5.0.0.CR4/vertx-core-logging-5.0.0.CR4.jar )
[INFO]  -> module: io.netty.common ( /path/to/my/mavenrepo/io/netty/netty-common/4.2.0.RC1/netty-common-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.resolver.dns ( /path/to/my/mavenrepo/io/netty/netty-resolver-dns/4.2.0.RC1/netty-resolver-dns-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.codec.http ( /path/to/my/mavenrepo/io/netty/netty-codec-http/4.2.0.RC1/netty-codec-http-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.codec.socks ( /path/to/my/mavenrepo/io/netty/netty-codec-socks/4.2.0.RC1/netty-codec-socks-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.codec.dns ( /path/to/my/mavenrepo/io/netty/netty-codec-dns/4.2.0.RC1/netty-codec-dns-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.transport ( /path/to/my/mavenrepo/io/netty/netty-transport/4.2.0.RC1/netty-transport-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.codec ( /path/to/my/mavenrepo/io/netty/netty-codec-base/4.2.0.RC1/netty-codec-base-4.2.0.RC1.jar )
[INFO]  -> module: io.netty.resolver ( /path/to/my/mavenrepo/io/netty/netty-resolver/4.2.0.RC1/netty-resolver-4.2.0.RC1.jar )
[INFO]  -> module: io.vertx.eventbusbridge ( /path/to/my/mavenrepo/io/vertx/vertx-bridge-common/5.0.0.CR4/vertx-bridge-common-5.0.0.CR4.jar )
[INFO] Building zip: /path/to/my/vertx-howtos/jlink-howto/target/jlink-howto-dist.zip

Running the application

Extract the target/jlink-howto-dist.zip archive somewhere on your disk. On Linux or other Unix-like systems, you can do this with the following command:

unzip -d target/jlink-howto target/jlink-howto-dist.zip

Inspect the total size of the custom runtime image folder. On Linux or other Unix-like systems, you can do this with the following command:

du -sh target/jlink-howto

On my machine, the result is 68 MB. In comparison, the total size of the JDK 11 distribution is 312 MB.

It’s time to give the application a try. On Linux or other Unix-like systems, you can do this with the following command:

target/jlink-howto/bin/server

You should see something like:

Feb 03, 2025 6:48:31 PM io.vertx.howtos.jlink.ServerVerticle lambda$start$1
INFO: HTTP server started on port 8888
Feb 03, 2025 6:48:31 PM io.vertx.launcher.application.VertxApplication
INFO: Succeeded in deploying verticle

Now, browse to http://localhost:8888 and verify that a greeting is displayed in the browser.

Note	When the launcher script is used, it’s not possible to specify VM options (heap size, remote debugging, etc.) as arguments. Instead, you can configure VM options in the JLINK_VM_OPTIONS environment variable.

Summary

This document covered:

1. creating a modular Vert.x Web application,

2. assembling a custom runtime image with jlink.

See also

• The Modular Vert.x Guide