In addition to the library and application plugins described in the following documentation, you can apply one of the following plugins to your project. For example, the minimal plugins can be used to reduce the number of tasks, for example if you don’t need Docker or GraalVM support:

Using the io.micronaut.application plugin:

is therefore equivalent to applying those plugins individually:

io.micronaut.minimal.application, io.micronaut.graalvm and io.micronaut.docker plugins (as well as the Eclipse annotation processing support plugin).

For Kotlin, the Kotlin jvm and kapt plugins must be configured:

With the io.micronaut.library plugin applied a minimal build to get started writing a library for Micronaut that written in Java and is tested with JUnit 5 looks like:

With the io.micronaut.application plugin applied a minimal build to get started with a Micronaut server application that is written in Java and tested with JUnit 5 looks like:

The most simple Kotlin build using a build.gradle(.kts) file looks like:

Since version 3.0.0, the Micronaut plugins rely on the official GraalVM plugin to build native images.

Those plugins make use of the Gradle toolchains support, which means that the SDK which is used to build the native is decorrelated from the JVM which is used to launch Gradle itself. Said differently, you can run Gradle with OpenJDK, while still building native images using the GraalVM SDK.

The Micronaut Gradle plugin will automatically configure the toolchains support for you, but there are a few things that you should be aware of:

If you have several GraalVM installations available, or that you want to disable the automatic toolchain recognition, we recommend that you do the following:

Alternatively you can pass those options from the command line:

You can build a native image by running the following task:

And you can run it by calling the following task:

You can tweak the native image options by configuring the graalvmNative extension as explained in the plugin documentation.

For example you can add options to the main image by doing:

Since 1.1.x of the plugin, you can also use the testNativeImage task to start the Micronaut native server and run tests against it.

Using this task will replace the regular embedded server used for tests with the natively built executable:

It is important to note that there are some limitations to this approach in that the native server is no longer "embedded" in the test. This has the following implications:

If you wish to split your native image tests from your regular tests you can create an additional source set for integration tests and the plugin will add an additional task suffixed with *NativeImage to run the native image tests, for example: gradle integrationTestNativeImage.

The Micronaut plugin includes integration with the Gradle Docker plugin allowing you to easily build applications and native images using Docker containers.

Applications are built as layered JARs using the buildLayers task ensuring optimized Docker images for Java applications.

To build a regular Java application into a Docker container that is ready to be deployed and exposes ports 8080 you can simply do:

The default uses an openjdk:17-alpine base image, however you can easily switch the base image to use by using the baseImage property of the dockerfile task:

The above examples switches to use GraalVM CE 20.3.0 as a base image.

To build the application into a Native Image you can run:

Note that for this to work you must build the application with the same GraalVM SDK as used to build the image.

To push the container to the currently configured container registry you can use either dockerPush or dockerPushNative for the native image:

To configure the image names to push you can use the images setting of the dockerBuild task.

For example the following configures dockerPush to use Oracle Container Registry:

Notice that you can supply two different image names to push to for the JVM version and the native version of the application.

If you wish to customize the docker builds that are used, the easiest way is to run ./gradlew dockerfile (or dockerfileNative for the native version) and copy the generated Dockerfile from build/docker to your root directory and modify as required.

If you wish to customize the JVM arguments or native image arguments then it is possible to do so with the args method of the dockerfile and dockerfileNative tasks:

The above configuration uses a max heap setting of 128m for Java and 64m for native image for the application.

To add additional docker instructions to the generated Dockerfile, such as adding a HEALTHCHECK, you can do the following. The additional instructions will be added at the end of the Dockerfile just before the ENTRYPOINT.

You can also add any of the other instructions/commands that the docker plugin supports, see the Dockerfile task documentation.

A higher level concept of "runtimes" is included in the Micronaut Gradle plugin which essentially allows the plugin to decide which server runtime to include in the dependencies of the application when building the application. For example consider this minimal build:

Here the only dependency declared is on the logging framework to use however runtime is to netty resulting in an application that can be built and run.

If you wish to take the same and build or run it with a different runtime you can pass the micronaut.runtime property for the build. For example:

The above example run the application as a Google Cloud Function.

The available runtimes are:

The advantage of allowing your dependencies to be dictated by the runtime is that you can potentially take the same application and deploy it to any of the above runtimes without changes.

By default the plugin doesn’t create a runnable fatjar when running ./gradlew assemble. There are a couple of options:

The io.micronaut.aot plugin is an extension to the io.micronaut.application plugin.

This will add an aot DSL block to the micronaut extension, which can be used to enable optimizations:

In addition, you can use the aotPlugins configuration to declare additional AOT modules to be used:

Because Micronaut AOT is an extensible optimization engine, not all optimizations are known beforehand by the plugin, which means that not all of them may be accessible via the DSL. For this reason, it is possible to provide a Micronaut AOT configuration file instead:

If you want to know about all possible optimizations, you can run the createAotSampleConfigurationFiles which will generate a couple of sample files:

The build/generated/aot/samples/jit/jit.properties will contain the optimizations which are relevant to an application running in the regular Java virtual machine, for example:

Another file, build/generated/aot/samples/native/native.properties will contain the same, but with the options which are relevant to an application compiled to a native image:

For native images, it is important to always have the graalvm.config.enabled option set to true, otherwise the AOT optimizations will not be loaded. The plugin takes care of setting this flag to true for you.

It is important to understand that Micronaut AOT works at build time. Therefore, some optimizations like conversion of YAML files to Java configuration will effectively disable the ability to change the configuration at runtime.

The plugin provides a couple of tasks aimed at running an optimized application. The first one, optimizedJar, will simply run the AOT compiler and produce an "optimized" jar. If you want to run the application with the resulting jar, you will need to call the optimizedRun task instead, which will create the jar and then start the application.

If you also have the distribution plugin applied, the optimized jar will be used to create optimized distributions, in which case you can call the optimizedDistZip task to create a distribution zip, the optimizedDistTar to create an optimized distribution tar file, or installOptimizedDist to install the optimized application to the build/install directory.

The plugin supports building an optimized fat jar. You will need to apply the shadow plugin to enable this feature:

Then you can generate the fat jar by calling: ./gradlew optimizedJitJarAll. The task will generate a fat jar in the build/libs directory, that you can run using:

java -jar build/libs/myapp-0.1-all-optimized.jar

The plugin creates a new native binary called optimized. The GraalVM plugin will then automatically create a couple of tasks for you:

It is also possible to build an optimized application and package it into a Docker image. For this, you need to call ./gradlew optimizedDockerBuild. It will produce a docker image that you can start using docker run.

Alternatively, you can call ./gradlew optimizedDockerPush to push the generated image to your docker registry.

All configuration options which apply to the standard docker image are also available to the optimized Docker images.

This task also produces a Docker image, but it will build a native image containing the optimized application within a container, in order to produce a Docker image which runs the optimized application natively.

The 2 tasks which are available for this are:

When upgrading from the 2.x version of the plugins, you will need to change the configuration of the GraalVM native image builds if you use them.

Typically, instead of configuring image compilation using the task:

You now need to use the graalvmNative extension. This extension supports building multiple native images, and the main one is named main (there is another one for tests, called test, which runs unit tests natively):

Similarly, to compile the native image, you now need to run nativeCompile instead of nativeImage.

In addition, the official GraalVM plugin makes use of Gradle toolchains support, which can lead to surprising behavior if you are used to switching between local JDKs. If you are facing errors like this one:

then we recommend tweaking toolchain detection as described in this section of the documentation.

In any case, make sure to follow the configuration instructions.