Smaller Java apps in Docker

This project showcases two features of the JDK:

• ability to create custom runtime for your application

• native support for Alpine Linux

Those both boil down to more efficient container usage. Spacewise.

Creating a custom runtime for your app means that you can drop all the useless modules from your packaging. Like in this example, why should a server application ship with all the user interface toolkits that Java ships with (AWT, Swing, and JavaFX).

Being able to put that custom runtime natively on Alpine Linux gives you really slim end result. People are routinely using Alpine Linux for small containers, and community has maintained a patched JRE for Java people. That was fine for a long time, but now we no longer have to use an unofficial JRE.

Results

The end result will be that you’ve got a pretty small, but functional, docker image for a Java app:

$ docker images
REPOSITORY                     TAG           IMAGE ID      CREATED         SIZE
vmj0/http-server-linux-java11  1.0-SNAPSHOT  ef252ec83afd  11 minutes ago  101MB
vmj0/http-server-alpine-java11 1.0-SNAPSHOT  7854466a32f3  12 minutes ago  35.2MB
alpine                         3.6           77144d8c6bdc  3 months ago    3.97MB
vbatts/slackware               13.37         777ef0cd51ed  6 months ago    69.8MB

As can be seen from above, the vmj0/http-server-alpine-java11 is less than half of the vmj0/http-server-linux-java11. The latter is based on a typical linux distro, vbatts/slackware in this case.

Below, I will show you the commands you can use to manually come up with above result. It will be a lot of typing, and in reality you would use a build tool to automate it.

Starting point

You will need a recent JDK, version 9 or above. I’m using JDK 9 even though it has been obsoleted by JDK 10.

$ java -version
openjdk version "9.0.4"
OpenJDK Runtime Environment (build 9.0.4+11)
OpenJDK 64-Bit Server VM (build 9.0.4+11, mixed mode)

As you probably know, JDK was modularized. Let’s see how many modules this JDK alone has:

$ java --list-modules |wc -l
      73

In order to follow these steps, you will also need Docker and git installed.

Clone this repository

$ git clone https://github.com/vmj/http-server.git
$ cd http-server

Compile the Java source code to class files

This project has just two Java files: the module info and the main class. The compilation is nothing new:

$ rm -rf build/classes/main
$ mkdir -p build/classes/main
$ javac -d build/classes/main \
    src/main/java/module-info.java \
    src/main/java/fi/linuxbox/http/Main.java

Run the class files as a module

Since we have the module-info in there, we can put the class files on the module path as opposed to classpath, and run the module:

$ java --module-path build/classes/main \
    -m http.server/fi.linuxbox.http.Main

After testing (see below), use CTRL-C or similar to interrupt the application.

Test

While the server is running, hit it with requests. E.g.:

$ curl http://localhost:9000/
Hello World

This little server also supports the HEAD method:

$ curl --head http://localhost:9000/
HTTP/1.1 200 OK
Date: Sun, 18 Jun 2017 15:37:11 GMT
Content-type: text/plain; charset=utf-8

And OPTIONS (note the Allow header in the response):

$ curl -v -X OPTIONS http://localhost:9000/
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 9000 (#0)
> OPTIONS / HTTP/1.1
> Host: localhost:9000
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Sun, 18 Jun 2017 15:37:21 GMT
< Allow: GET, OPTIONS
< Content-type: text/plain; charset=utf-8
< Content-length: 0
<
* Connection #0 to host localhost left intact

Package the class files as a modular JAR

The class files by themselves are a bit inconvenient to ship, so let’s build a modular JAR:

$ rm -rf build/jmods
$ mkdir -p build/jmods
$ jar --create --file build/jmods/http-server-1.0-SNAPSHOT.jar \
    --main-class fi.linuxbox.http.Main \
    -C build/classes/main .

As you can see, there’s nothing new here: our javac and jar invocations look exactly like they used to.

Run the modular JAR

Now running the application looks like this:

$ java --module-path build/jmods -m http.server

We’re just putting the JAR, instead of the class files, on the module path. Also, there’s no need to specify the main class anymore.

To verify that it works, you can go through the Test section again.

Create a custom runtime

The modular JAR is a fine distribution form for libraries, but for applications we can do a bit better.

One of the coolest features that came with JDK 9, IMHO, is the jlink command. It allows you to build a custom runtime just for your app.

For convenience, let’s define an environment variable that points to the JDK modules. You will need to adjust the directory here, since this one is specific to my setup. You can find the jmods directory from within your Java installation.

$ export TARGET_JMODS=/Users/vmj/.sdkman/candidates/java/9.0.4-openjdk/jmods

Note	While you can use JDK 9 to compile and package (as a JAR) your code, you can’t use JDK 9 jlink if you are building a custom runtime for Java 10 or 11. The major version number of jlink has to match the major version number of the JDK modules. We will address this further down.

Now, here’s the basic usage of jlink:

$ jlink --module-path build/jmods:$TARGET_JMODS \
    --add-modules http.server \
    --output build/jre/native

It will analyze the http.server module dependencies transitively, and spit out a small runtime:

$ du -csh build/jre/native
 35M    build/jre/native
 35M    total
$ build/jre/native/bin/java --list-modules
http.server
[email protected]
[email protected]
[email protected]

So now you’ve got a 35MB directory that includes your app, its dependencies, and a java executable. You’re down from 74 modules (73 for the JDK and 1 for your app) to just 4 modules. Nice :)

Optimize the custom runtime

Turns out that you can shrink the custom runtime even more. Let’s build it again with some more flags:

$ rm -rf build/jre/native
$ jlink --module-path build/jmods:$TARGET_JMODS \
      --strip-debug --vm server --compress 2 \
      --class-for-name \
      --exclude-jmod-section=headers --exclude-jmod-section=man \
      --dedup-legal-notices=error-if-not-same-content \
      --add-modules http.server \
      --output build/jre/native
$ du -csh build/jre/native
 21M    build/jre/native
 21M    total

That’s more than 40% off of an already small base :)

Run the module in the custom runtime

Just to check that things are still working, you can run the app using the custom runtime like this:

$ ./build/jre/native/bin/java -m http.server

And the Test section should look familiar by now.

Now you could zip that directory and send it to everyone who’s using the same platform as you are. (That’s why I chose the name native.)

Containerize the custom runtime

In order to be platform agnostic (this is Java app after all), we can Dockerize the custom runtime.

Note	the custom runtime needs to be cross-compiled for Linux, because that’s what’s running in the container. Don’t worry, JDK folks have made it child’s play :)

Most of the Linux distributions use the GNU C library known as glibc. Alpine Linux, in order to shrink the size of the distribution, is based on musl C library. Hence, the "normal" Linux JDK builds are not compatible with that because they are linked against glibc.

Luckily, Project Portola ported the JDK to Alpine Linux, and their effort was already included in the JDK 9 EA build 171, released at the beginning of June 2017. As of this writing, there doesn’t seem to be JDK 9 or 10 builds available anymore, but the latest JDK 11 for Alpine Linux is available at the Early Access page.

Download and extract the target JDK(s)

So, in order to cross-compile, you will need to download the target JDK. JRE is not enough. Also, you will need a matching native JDK for the linking to work.

You don’t have to install these JDKs, just extract them somewhere.

Head on to http://jdk.java.net/11/ and grab your native JDK and the Alpine Linux JDK. If you want to compare to a Linux distribution that is based on glibc, grab the Linux JDK, too. (Unless that happens to be your native platform.)

Then extract the JDK(s) somewhere. For example, I’ve got the Alpine JDK in /Users/vmj/jdks/x64-musl/ and Linux JDK in /Users/vmj/jdks/x64-linux/.

$ cd ~/jdks/x64-musl
$ tar xzf openjdk-11-ea+11_linux-x64-musl_bin.tar.gz
$ cd ../x64-linux
$ tar xzf openjdk-11-ea+12_linux-x64_bin.tar.gz
$ cd ../x64-osx
$ tar xzf openjdk-11-ea+12_osx-x64_bin.tar.gz

Cross-compile the custom runtime(s)

Point your TARGET_JMODS env var to the target JDK. Here I’m pointing it to Alpine Linux modules:

$ export TARGET_JMODS=/Users/vmj/jdks/x64-musl/jdk-11/jmods

And for convenience, point JLINK env var to the matching native jlink. Since I have JDK 9 as my regular JDK, I point the JLINK to the JDK 11 version I extracted above:

$ export JLINK=/Users/vmj/jdks/x64-osx/jdk-11.jdk/Contents/Home/bin/jlink

Now go back to the project directory and build the custom runtime for Alpine:

$ $JLINK --module-path build/jmods:$TARGET_JMODS \
      --strip-debug --vm server --compress 2 \
      --class-for-name \
      --exclude-jmod-section=headers --exclude-jmod-section=man \
      --dedup-legal-notices=error-if-not-same-content \
      --add-modules http.server \
      --output build/jre/alpine

Note that we’re now pointing the module path to the target JDK instead of that of the build host. jlink, which we launch from the native JDK, will notice that we’re cross-compiling, and it will spit out a different result.

We’re also changing the output directory, just so we can have multiple custom runtimes.

You can optionally run jlink again with TARGET_JMODS pointing to the Linux JDK and with the option --output build/jre/linux. That will give you a glibc based runtime for comparison.

$ export TARGET_JMODS=/Users/vmj/jdks/x64-linux/jdk-11/jmods
$ $JLINK --module-path build/jmods:$TARGET_JMODS \
      --strip-debug --vm server --compress 2 \
      --class-for-name \
      --exclude-jmod-section=headers --exclude-jmod-section=man \
      --dedup-legal-notices=error-if-not-same-content \
      --add-modules http.server \
      --output build/jre/linux

Prepare the Dockerfile(s)

Let’s create some simplistic Dockerfiles for our images:

$ rm -rf build/dockerfile
$ mkdir -p build/dockerfile
$ sed -e 's BASE_IMAGE alpine:3.6 ' Dockerfile.in >build/dockerfile/alpine
$ sed -e 's BASE_IMAGE vbatts/slackware:13.37 ' Dockerfile.in >build/dockerfile/linux

The second sed invocation is optional. In it, you could also use debian:stretch-slim or pretty much any glibc based Linux distribution.

Build the Docker image(s)

Now we can do the docker dance. First create a docker build context:

$ rm -rf build/docker
$ mkdir -p build/docker

Then copy the custom runtime and the Dockerfile to the build context:

$ cp -a build/jre/alpine build/docker/jre
$ cp build/dockerfile/alpine build/docker/Dockerfile

Now you can upload the build context to the docker daemon and build the image:

$ (cd build/docker && docker build --tag vmj0/http-server-alpine-java11:1.0-SNAPSHOT .)

And, you can do the same dance for Linux, just replacing alpine with linux in three places:

$ rm -rf build/docker
$ mkdir -p build/docker
$ cp -a build/jre/linux build/docker/jre
$ cp build/dockerfile/linux build/docker/Dockerfile
$ (cd build/docker && docker build --tag vmj0/http-server-linux-java11:1.0-SNAPSHOT .)

Run the container image

Running the container is old news:

docker run --rm -it -p9000:9000 vmj0/http-server-alpine-java11:1.0-SNAPSHOT

And checking that it works is…​ yes, in the Test section.

Some addition options

Above is all very tedious. But now that the process is known, you can use whatever build tool that you’re comfortable with. Here are a couple of examples.

Multistage Dockerfile

You can build the Alpine Docker image in one command using the Dockerfile.multistage, which was contributed by @StevenACoffman (thanks!). For example:

docker build -f Dockerfile.multistage --tag vmj0/http-server-multistage:1.0-SNAPSHOT .

Makefile

You probably noticed the Makefile. It’s optional, since I’ve shown you above how to do things, but the Makefile contains all the above commands.

If you’ve got GNU make, try invoking make help. Or do the following (adjusting variables, naturally) and read the help later:

$ unset TARGET_JMODS
$ export NATIVE_JMODS=/Users/vmj/jdks/x64-osx/jdk-11.jdk/Contents/Home/jmods
$ export ALPINE_JMODS=/Users/vmj/jdks/x64-musl/jdk-11/jmods
$ export LINUX_JMODS=/Users/vmj/jdks/x64-linux/jdk-11/jmods
$ for target in native alpine linux ; do make jre TARGET=$target ; done
$ export DOCKER_NAME=vmj0
$ for target in alpine linux ; do make dockerImage TARGET=$target ; done

Have fun!