Building a Native Executable

Building a native executable requires using a distribution of GraalVM. There are three distributions: Oracle GraalVM Community Edition (CE), Oracle GraalVM Enterprise Edition (EE) and Mandrel. The differences between the Oracle and Mandrel distributions are as follows:

GraalVM for JDK 21 is required.

On Linux it’s possible to package a native executable that doesn’t depend on any system shared library. There are some system requirements to be fulfilled and additional build arguments to be used along with the native-image invocation, a minimum is -Dquarkus.native.additional-build-args="--static","--libc=musl".

Compiling fully static binaries is done by statically linking musl instead of glibc and should not be used in production without rigorous testing.

By default, integration tests both build and run the native executable using the prod profile.

You can override the profile the executable runs with during the test using the quarkus.test.native-image-profile property. Either by adding it to application.properties or by appending it to the command line: ./mvnw verify -Dnative -Dquarkus.test.native-image-profile=test. Your %test. prefixed properties will be used at the test runtime.

You can override the profile the executable is built with and runs with using the quarkus.profile=test property, e.g. ./mvnw clean verify -Dnative -Dquarkus.profile=test. This might come handy if there are test specific resources to be processed, such as importing test data into the database.

With the aforementioned example in your application.properties, your Hibernate ORM managed database will be populated with test data both during the JVM mode test run and during the native mode test run. The production executable will contain only the version.txt resource, no superfluous test data.

When running tests this way, the only things that actually run natively are your application endpoints, which you can only test via HTTP calls. Your test code does not actually run natively, so if you are testing code that does not call your HTTP endpoints, it’s probably not a good idea to run them as part of native tests.

If you share your test class between JVM and native executions like we advise above, you can mark certain tests with the @DisabledOnIntegrationTest annotation in order to skip them when testing against a native image.

It is also possible to re-run the tests against a native executable that has already been built. To do this run ./mvnw test-compile failsafe:integration-test -Dnative. This will discover the existing native image and run the tests against it using failsafe.

If the process cannot find the native image for some reason, or you want to test a native image that is no longer in the target directory you can specify the executable with the -Dnative.image.path= system property.

By far the easiest way to create a container-image from your Quarkus application is to leverage one of the container-image extensions.

If one of those extensions is present, then creating a container image for the native executable is essentially a matter of executing a single command:

See the Container Image guide for more details.

You can run the application in a container using the JAR produced by the Quarkus Maven Plugin. However, in this section we focus on creating a container image using the produced native executable.

When using a local GraalVM installation, the native executable targets your local operating system (Linux, macOS, Windows etc). However, as a container may not use the same executable format as the one produced by your operating system, we will instruct the Maven build to produce an executable by leveraging a container runtime (as described in this section):

The produced executable will be a 64-bit Linux executable, so depending on your operating system it may no longer be runnable. However, it’s not an issue as we are going to copy it to a container. The project generation has provided a Dockerfile.native-micro in the src/main/docker directory with the following content:

Then, if you didn’t delete the generated native executable, you can build the docker image with:

And finally, run it with:

The project generation has also provided a Dockerfile.native in the src/main/docker directory with the following content:

The UBI minimal image is bigger than the micro one mentioned above. It contains more utilities such as the microdnf package manager.

The previous section showed you how to build a native executable using Maven or Gradle, but it requires you to have created the native executable first. In addition, this native executable must be a Linux 64 bits executable.

You may want to build the native executable directly in a container without having a final container containing the build tools. That approach is possible with a multi-stage Docker build:

Such a multi-stage build can be achieved as follows:

Sample Dockerfile for building with Maven:

Save this file in src/main/docker/Dockerfile.multistage as it is not included in the getting started quickstart.

Sample Dockerfile for building with Gradle:

If you are using Gradle in your project, you can use this sample Dockerfile. Save it in src/main/docker/Dockerfile.multistage.

And, finally, run it with:

If you are looking for small container images, the distroless approach reduces the size of the base layer. The idea behind distroless is the usage of a single and minimal base image containing all the requirements, and sometimes even the application itself.

Quarkus provides a distroless base image that you can use in your Dockerfile. You only need to copy your application, and you are done:

Quarkus provides the quay.io/quarkus/quarkus-distroless-image:2.0 image. It contains the required packages to run a native executable and is only 9Mb. Just add your application on top of this image, and you will get a tiny container image.

Distroless images should not be used in production without rigorous testing.

Building fully statically linked binaries enables the usage of a scratch image containing solely the resulting native executable.

Sample multistage Dockerfile for building an image from scratch:

Scratch images should not be used in production without rigorous testing.

Quarkus can compress the produced native executable using UPX. More details on UPX Compression documentation.

In certain circumstances, you may want to build the native image in a separate step. For example, in a CI/CD pipeline, you may want to have one step to generate the source that will be used for the native image generation and another step to use these sources to actually build the native executable. For this use case, you can set the additional flag quarkus.native.sources-only=true. This will execute the java compilation as if you had started native compilation (-Dnative), but stops before triggering the actual call to GraalVM’s native-image.

After compilation has finished, you find the build artifact in target/native-sources:

From the output above one can see that, in addition to the produced jar file and the associated lib directory, a text file named native-image.args was created. This file holds all parameters (including the name of the JAR to compile) to pass along to GraalVM’s native-image command. A text file named graalvm.version was also created and holds the GraalVM version that should be used. If you have GraalVM installed and it matches this version, you can start the native compilation by executing:

The process for Gradle is analogous.

Running the build process in a container is also possible:

-Dquarkus.native.container-build=true will produce an additional text file named native-builder.image holding the docker image name to be used to build the native image.

A high level overview of what the various steps of a CI/CD pipeline would look is the following:

The environment executing step 1 only needs Java and Maven (or Gradle) installed, while the environment executing step 3 only needs a GraalVM installation (including the native-image feature).

Depending on what the final desired output of the CI/CD pipeline is, the generated binary might then be used to create a container image.