This demo shows how to build, package, and run a simple Spring Boot 3 microservice from a JAR file with the GraalVM JDK, and from a native executable with GraalVM Native Image. The benefits of using a native executable are faster start-up times and reduced memory consumption. It also demonstrates how to run the application and build the native executable within a Docker container.
There are two ways to generate a native executable from a Spring Boot application:
The example is a minimal REST-based API application, built on top of Spring Boot 3. It consists of:
com.example.jibber.JibberApplication
: the main Spring Boot class. It is also a REST controller which serves as an entry-point for HTTP requests.com.example.jibber.Jabberwocky
: a utility class that implements the logic of the application.
If you call the HTTP endpoint, /jibber
, it will return some nonsense verse generated in the style of the Jabberwocky poem, by Lewis Carroll. The program achieves this by using a Markov Chain to model the original poem (this is essentially a statistical model). This model generates a new text. The example application provides the text of the poem, then generates a model of the text, which the application then uses to generate a new text that is similar to the original text. The application uses the RiTa library as an external dependency to build and use Markov Chains.
By default, the demo uses the Native Build Tools Maven plugin to perform the tasks. If you would like to run this demo using BuildPacks, the build configuration is provided for you too.
-
Download and install the latest GraalVM JDK using SDKMAN!.
sdk install java 21.0.2-graal
-
(Optional) Install and run a Docker-API compatible container runtime such as Rancher Desktop, Docker, or Podman. If you are using Docker, configure it to allow non-root user access if you are on Linux.
-
Download the demos repository or clone it as follows:
git clone https://github.com/graalvm/graalvm-demos
-
Change directory to the demo subdirectory:
cd spring-native-image
This demo is built using Maven.
-
Build the application on top of a JVM:
./mvnw clean package
It generates a runnable JAR file that contains all of the application’s dependencies and also a correctly configured
MANIFEST
file. -
Run the application JAR and put it into the background by appending
&
:java -jar ./target/benchmark-jibber-0.0.1-SNAPSHOT.jar &
-
Open the application http://localhost:8080/jibber in a browser, or call the endpoint using
curl
:curl http://localhost:8080/jibber
It should generate a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.
-
Bring the application to the foreground using
fg
, and then enter<CTRL-c>
to terminate the application.
The following steps (5-8) show how you can easily containerize the JAR built in the previous step using the Oracle GraalVM JDK container image container-registry.oracle.com/graalvm/jdk:17-ol8
.
-
Run this command to package the JAR as a Docker container:
docker build -f Dockerfiles/Dockerfile.jvm --build-arg APP_FILE=benchmark-jibber-0.0.1-SNAPSHOT.jar -t jibber-benchmark:jvm.0.0.1-SNAPSHOT .
-
Run the container:
docker run --rm --name graal -p 8080:8080 jibber-benchmark:jvm.0.0.1-SNAPSHOT
-
Open the application http://localhost:8080/jibber in a browser, or from a new terminal window, call the endpoint using
curl
:curl http://localhost:8080/jibber
You should get a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.
-
To stop the application, first get the container id using
docker ps
, and then run:docker rm -f <container_id>
Recap what you have so far: built a Spring Boot application with an HTTP endpoint, and successfully containerised it. Now you will look at how you can create a native executable from your application.
Spring Boot 3's built-in support for GraalVM Native Image makes it easy to compile a Spring Boot 3 application into a native executable.
This native executable not only starts faster but also uses far fewer resources than running the application as a JAR file.
You can use the native-image
tool from the GraalVM installation to build a native executable.
In this example, you'll use the GraalVM Native Build Tools for Maven to build a native executable.
Make sure you’re using spring-boot-starter-parent
in order to inherit the out-of-the-box native
profile, and the org.graalvm.buildtools:native-maven-plugin
plugin.
You should see the following in the Maven pom.xml
file:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.0</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
</plugin>
...
</plugins>
</build>
The out-of-the-box native
profile has GraalVM Reachability Metadata enabled by default.
With the out-of-the-box native
profile active, you can invoke the native:compile
goal to trigger native-image compilation.
-
Run the following command:
./mvnw native:compile -Pnative
The
native
profile is used to generate a native executable for your platform. The native executable is called benchmark-jibber and is generated in the target directory.Alternatively, to build using BuildPacks, run the
./mvnw spring-boot:build-image -Pnative
command to generate a native executable. For more information about using BuildPacks to create a native executable, see Building a Native Image Using Buildpacks. -
Run the native executable and put it into the background by appending
&
:./target/benchmark-jibber &
-
Open the application http://localhost:8080/jibber in a browser, or call the endpoint using
curl
:curl http://localhost:8080/jibber
You should get a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.
-
Bring the application to the foreground using
fg
, and then enter<CTRL-c>
to terminate the application.
From the log output, notice how much quicker the native executable version of this Spring Boot application starts compared to the JAR. The native executable also uses fewer resources than running from a JAR file.
Notice that you can pass additional configuration arguments to the underlying native-image
build tool using the <buildArgs>
section. In individual buildArg
tags, you can pass parameters exactly the same way as you do from a command line. This lets you use all of the parameters that work with the native-image
tool from Maven.
Add the following snippet to the pom.xml to pass additional arguments to enable verbose output, quick build mode, etc. over and above the out-of-the-box native
profile.
<profiles>
<profile>
<id>native</id>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<!--<version>0.9.28</version>-->
<configuration>
<verbose>true</verbose>
<quickBuild>true</quickBuild>
<buildArgs combine.children="append">
<arg>-H:+ReportExceptionStackTraces</arg>
</buildArgs>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
Let's rebuild the native executable with the additional configuration arguments.
-
Run the following command:
./mvnw native:compile -Pnative
With the quick build mode enabled, it takes less time to build the native executable. This mode should be used in development for faster builds.
-
Run the native executable and put it into the background by appending
&
:./target/benchmark-jibber &
-
Open the application http://localhost:8080/jibber in a browser, or call the endpoint using
curl
:curl http://localhost:8080/jibber
You should get a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.
-
Bring the application to the foreground using
fg
, and then enter<CTRL-c>
to terminate the application.
From the log output, notice how much quicker the native executable version of this Spring Boot application starts compared to the JAR. The native executable also uses fewer resources than running from a JAR file.
The following steps (5-8) are for Linux only.
-
On Linux, you can easily containerise the native executable using the following command:
docker build -f Dockerfiles/Dockerfile.native --build-arg APP_FILE=benchmark-jibber -t jibber-benchmark:native.0.0.1-SNAPSHOT .
-
Run the application:
docker run --rm --name native -p 8080:8080 jibber-benchmark:native.0.0.1-SNAPSHOT
-
Open the application http://localhost:8080/jibber in a browser, or from a new terminal window, call the endpoint using
curl
:curl http://localhost:8080/jibber
It should generate a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.
-
To stop the application, first get the container id using
docker ps
, and then run:docker rm -f <container_id>
(Optional) Use Multistage Docker Builds to Build a Native Image and Package it in a Lightweight Container
The following steps (9-12) are for all platforms - MacOS, Windows, and Linux.
For MacOS and Windows, to build a Docker image containing your native executable, you need to build the native executable inside a Docker container. To do this, we've provided a multistage Docker build file.
-
Run this command to build the native executable within a Docker container:
docker build -f Dockerfiles/Dockerfile -t jibber-benchmark:native.0.0.1-SNAPSHOT .
-
Run the application:
docker run --rm --name native -p 8080:8080 jibber-benchmark:native.0.0.1-SNAPSHOT
-
Open the application http://localhost:8080/jibber in a browser, or from a new terminal window, call the endpoint using
curl
:curl http://localhost:8080/jibber
It should generate a random nonsense verse in the style of the poem Jabberwocky by Lewis Carrol.
-
To stop the application, first get the container id using
docker ps
, and then run:docker rm -f <container_id>
The Spring Actuator dependency has been added to the project, along with support for Prometheus. If you want to test the performance of either the JVM version, or the native executable version of the application, you can make use of the Prometheus support. If you are hosting the application locally, it is available on port 8080: