These tutorials target Micronaut Framework 3. Read, Guides for Micronaut Framework 4.

Building a Docker Image of your Micronaut application

Micronaut build plugins offer several ways to build Docker images - JAR, GraalVM native executable, CRaC

Authors: Sergio del Amo

Micronaut Version: 3.9.2

1. Getting Started

In this guide, we will create a Micronaut application written in Kotlin.

2. What you will need

To complete this guide, you will need the following:

  • Some time on your hands

  • A decent text editor or IDE

  • JDK 1.8 or greater installed with JAVA_HOME configured appropriately

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=graalvm,crac,micronaut-aot \
    --build=gradle
    --lang=kotlin
If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add graalvm, crac, and micronaut-aot features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features and apply those changes to your application.

5. Building a Docker Image with the Micronaut Gradle Plugin

The Micronaut Gradle Plugin offers the following tasks to build Docker images:

  • dockerBuild - Builds a Docker Image using the Docker Gradle plugin

  • dockerBuildNative - Builds a Native Docker Image using GraalVM Native Image

  • optimizedDockerBuild - Build an optimized application and package it into a Docker image.

  • optimizedDockerBuildNative - Build a native image containing the optimized application and pakcage it into a Docker Image

6. Controller

Add a controller which responds with the JSON payload in the root route.

{"message":"Hello World"}
src/main/kotlin/example/micronaut/HelloController.kt
package example.micronaut

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller (1)
class HelloController {

    @Get (2)
    fun index() = mapOf("message" to "Hello World") (3)
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /.
2 The @Get annotation maps the method to an HTTP GET request.
3 The Micronaut framework will automatically convert it to JSON before sending it.

7. Time To First Request Measurement script

In this guide, we use the following script to measure time to first request of a Docker image.

src/main/../../ttfr.sh
#!/usr/bin/env bash

set -e

TYPE="docker"
PORT=8080
DELAY=20

usage() {
  echo "$0: Time to first request for native, java or docker applications"
  echo ""
  echo "  $0 [-d|-j|-n] [-p port] ARTIFACT"
  echo ""
  echo "    -d : ARTIFACT is a docker image (default)"
  echo "    -j : ARTIFACT is a fat jar"
  echo "    -n : ARTIFACT is a native executable"
  echo "    -p : port to check (default 8080)"
  echo ""
}

while getopts 'djnp:' flag; do
  case "${flag}" in
    d) TYPE="docker" ;;
    j) TYPE="java" ;;
    n) TYPE="native" ;;
    p) PORT="${OPTARG}" ;;
    *) usage
       exit 1 ;;
  esac
done
shift $(($OPTIND - 1))
echo $1

if [ $# -eq 0 ]; then
  echo "Needs the docker image or Jar file to run"
  exit 1
fi

execute() {
  local END=$((SECONDS+DELAY))
  while ! curl -o /dev/null -s "http://localhost:${PORT}"; do
    if [ $SECONDS -gt $END ]; then
      echo "No response from the app in $DELAY seconds" >&2
      exit 1
    fi
    sleep 0.001;
  done
}

mytime() {
  exec 3>&1 4>&2
  mytime=$(TIMEFORMAT="%3R"; { time $1 1>&3 2>&4; } 2>&1)
  exec 3>&- 4>&-
  echo $mytime
}

if [[ "$TYPE" == "java" ]]; then
  java -jar $1 &
  PID=$!
  TTFR=$(mytime execute)
  kill -9 $PID
elif [[ "$TYPE" == "docker" ]]; then
  CONTAINER=$(docker run -d --rm -p $PORT:$PORT --privileged $1)
  TTFR=$(mytime execute)
  docker container kill $CONTAINER > /dev/null
else
  $1 &
  PID=$!
  TTFR=$(mytime execute)
  kill -9 $PID
fi

if [ "$TTFR" != "" ]; then
    echo "${TTFR} seconds"
else
    exit 1
fi

7.1. Docker Image

Generate a Docker Image with:

./gradlew dockerBuild
...
..
.
Removing intermediate container 784f978688d1
 ---> e5c1b8b8dbcb
Successfully built e5c1b8b8dbcb
Successfully tagged micronautguide:latest
Created image with ID 'e5c1b8b8dbcb'.

Supply to image name and tag to the time to first request script:

./ttfr.sh micronautguide:latest
micronautguide:latest
...
.
2.473 seconds

7.2. Docker image with a GraalVM native executable inside

Generate a Docker Image with:

./gradlew dockerBuildNative
> Task :generateResourcesConfigFile
[native-image-plugin] Resources configuration written into /Users/sdelamo/github/micronaut-projects/micronaut-guides/build/code/micronaut-docker-image/micronaut-docker-image-gradle-java/build/native/generated/generateResourcesConfigFile/resource-config.json

> Task :dockerfileNative
Dockerfile written to: /Users/sdelamo/github/micronaut-projects/micronaut-guides/build/code/micronaut-docker-image/micronaut-docker-image-gradle-java/build/docker/native-main/DockerfileNative

> Task :dockerBuildNative
...
Step 1/14 : FROM ghcr.io/graalvm/native-image:ol7-java17-22.3.0 AS graalvm
 ....
....
....
========================================================================================================================
GraalVM Native Image: Generating 'application' (executable)...
========================================================================================================================
...
Step 14/14 : ENTRYPOINT ["/app/application"]
 ---> Running in 447363f48c82
Removing intermediate container 447363f48c82
 ---> 0b57ab829518
Successfully built 0b57ab829518
Successfully tagged micronautguide:latest
Created image with ID '0b57ab829518'.

BUILD SUCCESSFUL in 2m 26s

Run the time to first request script with the Native Docker Image:

./ttfr.sh micronautguide:latest
micronautguide:latest
...
.
0,047
seconds

8. CRaC Docker Image

Generate a Docker Image containing a CRaC enabled JDK and a pre-warmed, checkpointed application:

./gradlew dockerBuildCrac

...

Successfully built ba78619b8d86
Successfully tagged micronautguide:latest
Created image with ID 'ba78619b8d86'.

BUILD SUCCESSFUL in 1m 41s
13 actionable tasks: 9 executed, 4 up-to-date

Run the time to first request script with CRaC Docker Image:

./ttfr.sh micronautguide:latest
micronautguide:latest
...
.
0.462 seconds

8.1. AOT Optimized Docker Image

./gradlew optimizedDockerBuild

Run the time to first request script with AOT optimized Docker Image:

./ttfr.sh micronautguide:latest
micronautguide:latest
...
.
2,359 seconds

8.2. AOT Optimized Docker Image with a native executable inside

./gradlew optimizedDockerBuildNative

Run the time to first request script with AOT optimized Docker Image:

./ttfr.sh micronautguide:latest
micronautguide:latest
...
.
0.039 seconds

9. Comparisons

Micronaut Framework offers many options for packaging your application as a Docker Image. As illustrated in the following chart, you can speed up your Docker Images by using the GraalVM integration in the Micronaut Framework, the CRaC (Coordinated Restore at checkpoint) integration in the Micronaut Framework, Micronaut AOT Gradle Plugin or Maven Plugin integration with Micronaut AOT.

The following chart illustrates the speed gains you can obtain:

docker image ttfr

Docker Image

2s 473ms

Optimized Docker Image

2s 359ms

CRaC Docker Image

462ms

Native Docker Image

47ms

Optimized Native Docker Image

39ms

I used the following hardware to calculate the previous benchmarks

Characteristic

Value

Model Name

iMac Pro 2017

Processor

3GHz 10-Core Intel Xeon W

Memory

32 GB 2666 MHz DDR4

Total Number of Cores

10

Operating System

Mac OS X 10.15.7 (Mojave)

10. Next steps

Explore more features with Micronaut Guides.

Learn more about:

11. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.