Java: Developing smaller Docker images with jdeps and jlink

Tech stack: Java 17, Docker, Gradle

Figure 1: Pipeline for creating a custom JRE when building smaller Docker images with Java.

With the rise of containers and immutable infrastructure, some of the benefits of having a large and dynamic virtual machine have been lost. There is no longer a need to have an extensive runtime that can run any Java application, as you now test and ship your application with its own environment, from the JVM down to the OS. You also tend to know exactly which parts of the runtime you will be using for your application; why would we want to include (or even want to think about) the Java Swing libraries when we are running a server side application?

All of this means that Java can feel a bit bloated and difficult when comparing it to some more cloud native alternatives. So how can we ship smaller and more light weight containers, only including the things we explicitly need to run our application and still benefit from the Java ecosystem?

This is where 2 new tools have been created and now ship with the JDK: jdeps and jlink.

Jdeps is responsible for analysing a JAR, with its dependencies, and identifying the parts of the JVM needed to run the application. It can output this to a text file, which can then be consumed by jlink.

Jlink takes a list of JVM modules, and builds a custom JVM with only those parts present. Depending on your application, this can obviously cut out massive parts of the runtime, reducing your overall Docker image size.

In the rest of this guide, we will do the following:

1. Setup a Gradle project, where we have a Java application built and packaged.
2. Integrate Docker with Gradle, so we can build our application using the Gradle tooling.
3. Build a multi-stage Dockerfile that makes use of jdeps and jlink to significantly reduce our final Docker image size.

Step 1: Creating the starting Gradle project

Ensure you have gradle installed, or already have a gradle project setup.

To begin, we will create an empty Gradle project, then build out our Dockerfile to package and run a simple command line application.

Create a folder for your application to be stored in, and then run the following command from a terminal at the folder location:

gradle init --type java-application

This will then present you with a few options. None are too important for this guide, but here is the selection I chose for reference.

Figure 2: creating an empty gradle project. Selecting Groovy, JUnit Jupiter, and a project name of test-app.

With this starting point, go to the build.gradle file and copy this starting code in:

plugins {
    id 'java-library'
}

sourceCompatibility = '11'
version = '1.0.0'
repositories {
    mavenCentral()
    mavenLocal()
}

dependencies {
    implementation 'org.slf4j:slf4j-api:1.7.30'
    implementation 'org.apache.logging.log4j:log4j-api:2.11.1'
    implementation 'org.apache.logging.log4j:log4j-core:2.11.1'
    implementation 'org.apache.logging.log4j:log4j-slf4j-impl:2.11.1'

    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.2'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'
}

tasks.named('test') {
    // Use junit platform for unit tests.
    useJUnitPlatform()
}

The above code does the following:

• Provides basic Java compatibility with Gradle.
• Adds the log4j dependency so when we run jdeps in future steps we have dependencies to analyse.

To use log4j in our application, go to app/src/main/resources and add the following log4j2.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

This means when we add any INFO level logs, they will appear in the console.

Finally, go to src/main/java/…/App.java, and add the following content:

package test.app;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class App {

    private static final Logger LOG = LoggerFactory.getLogger(App.class);

    public String getGreeting() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        LOG.info("hello, the application has started");

        LOG.error(new App().getGreeting());

        LOG.info("the application is now complete");
    }
}

This means when we run our application, combined with our log4j configuration, we will print a few messages to the console before exiting.

With these changes implemented, you should be able to run the following command:

./gradlew clean check

You should see a nice ‘BUILD SUCCESSFUL’ message, which means you have initialised the starting project correctly and we are ready to move on to building an executable JAR.

Step 2: Creating an executable JAR

In order to use jdeps, for this guide, we will need to package our application as an executable JAR. Then we will need to copy all its dependencies to a separate folder.

In order to do this, add the following tasks to your build.gradle file:

// copies all the jar dependencies your app needs to the lib folder
task copyDependencies(type: Copy) {
    from configurations.runtimeClasspath
    into "$buildDir/lib"
}

// creates your manifest file within the JAR
jar {
    manifest {
        attributes["Main-Class"] = "test.app.App"
        attributes["Class-Path"] = configurations.runtimeClasspath.collect { 'lib/' + it.getName() }.join(' ')
    }
}

This does the following:

• copies all your application dependencies to the app/build/lib directory. This means when we want to run jdeps we can tell it the folder to use when resolving dependencies.
• sets the main class in our jar to be the class that holds the main method. If you created a different package structure, be sure to update this to match.
• sets the class path of the JAR, so when this jar is ran it will look for dependencies in the lib/ folder. This means we don’t build a fat jar, but instead set the location where all our external JARs can be found, which we then use both at runtime and when running the jdeps tool.

With this setup, we are ready to start integrating Docker.

Step 3: Integrating Docker

The first step to integrating Docker into our application, is to provide a way to run the docker build command as a Gradle task. This means we can use Gradle to ensure dependent steps are performed before docker is invoked (for instance making sure the JAR and dependencies are built and copied to the right location to then be copied into the Docker image).

In order to do this, add the following tasks to your build.gradle file:

// builds the docker image, tagging it with the same group id, name, and version as the JAR
task buildDocker(type: Exec) {
    dependsOn copyDependencies, build
    workingDir "$projectDir"
    commandLine 'docker', 'build', '--rm', '.', '-t', "$project.group/$project.name:$project.version", "-f", "$projectDir/src/main/docker/Dockerfile"
}
// runs the docker image
task runDocker(type: Exec) {
    dependsOn buildDocker
    workingDir "$projectDir"
    commandLine 'docker', 'run', "$project.group/$project.name:$project.version"
}

These tasks will do the following:

• buildDocker: ensure the app is built and copyDependencies has been ran. It then invokes the docker build command, looking for the Dockerfile in app/src/main/docker/Dockerfile.
• runDocker: simply ensures buildDocker has been ran and then invokes the docker run command on the newly built image.

Next, create the Dockerfile in app/src/main/docker/Dockerfile, adding the starting content of:

####
# This Dockerfile is used to package the yak-server application
#
# Build the image with:
#
# ./gradlew buildDocker
#
###

FROM openjdk:17-alpine AS jre-build
WORKDIR /app

# copy the dependencies into the docker image
COPY build/lib/* build/lib/

# copy the executable jar into the docker image
COPY build/libs/app-*.jar build/app.jar

# tempoarily test our JAR works when we run the image
WORKDIR /app/build
ENTRYPOINT java -jar app.jar

From this point, you should be able to run from the root of your project:

./gradlew clean runDocker

Where you should see the following happen:

• the JAR is built and put in the app/build/libs directory.
• the JAR dependencies are copied to the app/build/lib directory.
• the Docker image is built, copying both of those directories into it.
• the Docker image is ran, and you can see our Hello World! output to console.

This means we now have everything in place to begin optimising our Dockerfile using jdeps and jlink.

Important side note: before we begin optimising, it’s good to know where we are starting from. Right now, we have everything we would need to run this application normally, however if we look at our docker image size:

docker images

You will see something similar to:

Which shows we have around a 330Mb docker image for this command line application. With this in mind, let’s see how much smaller we can make that by using the new tooling.

Step 4: Using jdeps and jlink to create a smaller Docker image size

Using jdeps to find your required JVM modules

As we now have a starting point in the Dockerfile where we have access to the JAR we want to run and its dependencies, we can now invoke jdeps to analyse these and output the parts of the JVM we need at runtime.

To do this, edit your Dockerfile to contain the following:

####
# This Dockerfile is used to package the yak-server application
#
# Build the image with:
#
# ./gradlew buildDocker
#
###

FROM openjdk:17-alpine AS jre-build
WORKDIR /app

# copy the dependencies into the docker image
COPY build/lib/* build/lib/

# copy the executable jar into the docker image
COPY build/libs/app-*.jar build/app.jar

# find JDK dependencies dynamically from jar
RUN jdeps \
# dont worry about missing modules
--ignore-missing-deps \
# suppress any warnings printed to console
-q \
# java release version targeting
--multi-release 17 \
# output the dependencies at end of run
--print-module-deps \
# specify the the dependencies for the jar
--class-path build/lib/* \
# pipe the result of running jdeps on the app jar to file
build/app.jar > jre-deps.info

# temp print jdeps output
ENTRYPOINT cat /app/jre-deps.info

You can now see we invoke jdeps with the following:

• what version of Java we are targeting (in this example 17, which matches the base docker image we are building from).
• where to find the dependencies for the JAR.
• finally, we pipe the output of the command to a file jre-deps.info, which for now we just print to console when the docker image is ran.

With this, run the docker image:

./gradlew clean runDocker

You will see output of:

Which shows, in a comma separated list, the JVM modules we require when running our application. With this, we know exactly what our application needs at runtime, and we can now look at building a JRE that only includes these parts, significantly reducing the size of our final Docker image.

Using jlink to create a custom JRE

With the output of jdeps stored to file, we can now invoke jlink in order to build a custom JRE with only the provided modules. To do this, edit your Dockerfile to include the following:

####
# This Dockerfile is used to package the yak-server application
#
# Build the image with:
#
# ./gradlew buildDocker
#
###

FROM openjdk:17-alpine AS jre-build
WORKDIR /app

# copy the dependencies into the docker image
COPY build/lib/* build/lib/

# copy the executable jar into the docker image
COPY build/libs/app-*.jar build/app.jar

# find JDK dependencies dynamically from jar
RUN jdeps \
# dont worry about missing modules
--ignore-missing-deps \
# suppress any warnings printed to console
-q \
# java release version targeting
--multi-release 17 \
# output the dependencies at end of run
--print-module-deps \
# specify the the dependencies for the jar
--class-path build/lib/* \
# pipe the result of running jdeps on the app jar to file
build/app.jar > jre-deps.info
# new since last time!
RUN jlink --verbose \
--compress 2 \
--strip-java-debug-attributes \
--no-header-files \
--no-man-pages \
--output jre \
--add-modules $(cat jre-deps.info)

# take a smaller runtime image for the final output
FROM alpine:latest
WORKDIR /deployment

# copy the custom JRE produced from jlink
COPY --from=jre-build /app/jre jre

# copy the app dependencies
COPY --from=jre-build /app/build/lib/* lib/

# copy the app
COPY --from=jre-build /app/build/app.jar app.jar

# run the app on startup
ENTRYPOINT jre/bin/java -jar app.jar

Lets breakdown our final Dockerfile:

• we copy our app and dependencies into the docker image.
• we then run jdeps to find out the modules of the JRE we need for this specific application.
• we run jlink to build a custom, cut-down, JRE for this specific application.
• we take a new runtime image, making use of dockers multi-stage build process. This image is from alpine:latest so is very small.
• we copy our custom JRE, application, and it’s dependencies into this final cut down image.
• we set the entrypoint to run our application using the JRE produced from jlink.

If you have copied the following code correctly, you will see the application startup and print the “Hello World!” log message when you run:

./gradlew clean runDocker

So, we are back with our app successfully running within Docker, but the big question still remains… how much smaller is our final Docker image after going through all this trouble?

Currently, on my machine, my final docker image size is now: 58.6mb

docker images

Thats over 250mb smaller than the original image we started with!

I hope this guide has shown you how you can take a standard Java application and, with minimal work, create a minimised Docker image to run it within.

Quick side note: sometimes jdeps can be a pain to get working, especially if you have a complicated class path. You can always manually work out the modules you need, and simply pass this to the jlink command yourself. You may not get the most optimised image, but it can be a significant improvement over running the full JRE.

If you have any questions over this approach, feel free to reach out to me.

Joe Honour - Senior Software Engineer - AND Digital | LinkedIn