Assembling a small runtime image of a modular Vert.x application with jlink

This document will show you how to assemble a small runtime image of a modular Vert.x application with jlink.

What you need

• A text editor or an IDE

• Java 11 or higher

Create a project

Here is the content of the Maven 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 provides a factory for the main verticle to deploy:

CustomLauncher.java

Having the verticle factory in io.vertx.howtos.jlink.CustomLauncher simplifies the Java module configuration:

module-info.java

Indeed, since the verticle instance won’t be created via reflection, 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 Microsoft 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/java --module io.vertx.howtos.jlink/io.vertx.howtos.jlink.CustomLauncher

Or, you can use the generated server script:

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. You can either change the JLINK_VM_OPTIONS variable in the server script or use the java command. For example, for remote debugging on Linux or other Unix-like systems: target/jlink-howto/bin/java \ -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 \ --module io.vertx.howtos.jlink/io.vertx.howtos.jlink.CustomLauncher

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