Building and Running a Micronaut Application in a Docker Container

1. Introduction

In this tutorial, we’ll explore how to build and run a Micronaut application in a Docker container. We’ll discuss everything from setting up a Micronaut project to creating and running a Dockerized application.

Micronaut is a modern, JVM-based framework designed for building modular, easily testable microservices and serverless applications with minimal memory footprint. Docker simplifies the deployment process by allowing developers to package applications into containers that combine the necessary code, libraries, and dependencies to run uniformly across different environments.

When used together, Micronaut and Docker create a powerful duo for efficiently developing and deploying scalable and resilient applications.

2. Prerequisites

For an effective guide on building and running a Micronaut application in a Docker container, here’s what we’ll need upfront:

• Java Development Kit (JDK): JDK 21 is recommended for better performance and access to new language features. Micronaut does support JDK 17 as well, but we’ll need to ensure we change the version flags accordingly. In this tutorial, we’ll use JDK 21, as it’s Micronaut’s default version.
• Micronaut: Micronaut installation is optional since we can create a project on the web too. In this tutorial, we’ll learn how to do it using both the CLI and Micronaut’s website.
• Gradle or Maven: We’ll automate Docker image creation using Gradle and Maven, leveraging Micronaut’s built-in wrappers without additional installation.
• Docker: Docker should be installed and configured on our machine to facilitate containerization.

We’ll focus on using these tools to build our Docker container holding a Micronaut app, rather than the initial setup of these environments. We should ensure that we have them prepared to follow along seamlessly.

3. Setting up the Micronaut Application

To start setting up our Micronaut application we’ll first create a new Micronaut project. We can do this via Micronaut’s CLI, the Micronaut Launch website, or a compatible IDE such as IntelliJ IDEA.

3.1. Using the CLI

To install Micronaut CLI, we’ll follow Micronauts’ official documentation, which uses SDKMAN!. Once installed, we can use this command to create the project:

mn create-app com.baeldung.micronautdocker

This creates a basic Micronaut application scaffolding under the com.baeldung.micronautdocker package. By default, Micronaut sets up the project to be used with Java 21 and Gradle as the build tool.

To use Java 17 or Maven, we can include the appropriate flags:

mn create-app com.baeldung.micronautdocker --jdk 17 --build maven

We can see other flags and set-up options in Micronaut’s CLI Guide.

3.2. Using Micronaut Launch

If we want to skip Micronaut’s installation, we can create a new project using their Micronaut Launch Website. Unlike the CLI, the website allows us to download a folder with all the necessary files to get us working without needing any installation.

3.3. Checking the Environment

Once we’ve successfully created our project, we can check if everything is working by starting the application.

Here’s the command to launch the application using Gradle:

./gradlew run

If we use Maven, we can launch the application by invoking the mn:run target:

./mvnw mn:run

We can verify the application is running by navigating to http://localhost:8080 in a browser or using a tool like curl.

This step ensures everything is properly configured and our Micronaut application is set up correctly. Once we verify it, we can move forward and start Dockerizing our application.

4. Dockerizing the Application

With our Micronaut application set up and functioning correctly, the next step is to prepare it for Dockerization.

To create an auto-generated Docker image, we need to ensure that our build tool has some configurations to make it work properly. Both Gradle and Maven have built-in support for the creation of Docker images. Nevertheless, if we wanted to modify trivial Docker features, we’d need to do some setup.

In this section, we’ll change the base image, and exposed ports, add custom instructions, and change the output Docker image name.

4.1. Dockerizing With Gradle

To make modifications in the Dockerfile, we’ll need to capture Gradle tasks and add custom settings:

tasks.named<MicronautDockerfile>("dockerfile") {
    baseImage.set("eclipse-temurin:21-jre-alpine")
    exposedPorts.set(arrayListOf(9090))
    instruction("RUN echo 'Hello world!'")
}

In this code, we used baseImage.set() to change the name of the base image, exposedPorts.set() to change the ports that are going to be exposed by Docker, and instruction() to add a custom echo instruction.

If we want to change the output Docker image name, we’ll use:

tasks.named<DockerBuildImage>("dockerBuild") {
    images.set(listOf("micronaut_docker_gradle"))
}

This captures the dockerBuild task and sets the Docker image name to micronaut_docker_gradle. To learn more about modifying the Dockerfile from Gradle, we can go to the official Micronaut Gradle Plugin Docker Support Documentation.

4.2. Dockerizing Using Maven

Since the Micronaut Maven plugin doesn’t have built-in support for creating Docker images, we’ll use Jib from Google Cloud Tools. Jib is a popular plugin for building optimized Docker images directly from Maven without requiring a separate Dockerfile.

First, we’ll need to set up some variables in our properties section:

<properties>
    ...
    <docker.baseImage>eclipse-temurin:21-jre-alpine</docker.baseImage>
    <docker.exposedPort>9090</docker.exposedPort>
    <docker.imageName>micronaut_docker_maven</docker.imageName>
</properties>

Next, we configure the jib dockerBuild process. To do so, we’ll modify our plugins section in the build tag:

<build>
    <plugins>
     ...
        <plugin>
            <groupId>com.google.cloud.tools</groupId>
            <artifactId>jib-maven-plugin</artifactId>
            <version>3.3.1</version>
            <configuration>
                <from>
                    <image>${docker.baseImage}</image>
                </from>
                <container>
                    <ports>
                        <port>${docker.exposedPort}</port>
                    </ports>
                    <entrypoint>
                        <shell>sh</shell>
                        <option>-c</option>
                        <arg>
                            java -cp /app/resources:/app/classes:/app/libs/* ${exec.mainClass}
                        </arg>
                    </entrypoint>
                </container>
                <to>
                    <image>${docker.imageName}</image>
                </to>
            </configuration>
        </plugin>
    </plugins>
</build>

As demonstrated, jib doesn’t support custom instructions being written directly in the Dockerfile. We can reference the official Micronaut Maven Plugin Packaging Documentation.

5. Building the Docker Image

With our application packaged and ready, we’ll focus on how to build, check, and run our Docker image.

Here’s the command to build the image using Gradle:

./gradlew dockerBuild

If we use Maven, we can launch the application by invoking the jib:dockerBuild target:

./mvnw jib:dockerBuild

After running the dockerBuild command, we can confirm the image was created by listing local Docker images:

docker images

After running these commands, we should see the Docker image listed with the name micronaut_docker_gradle or micronaut_docker_maven. This confirms that our Docker image is ready to be deployed.

6. Running the Container

With the Docker image built, the next step is to run it as a container.

Here’s the command to start the container using Gradle:

docker run -p 9090:9090 micronaut_docker_gradle:latest

If we use Maven, we can start the container by running the image created for Maven:

docker run -p 9090:9090 micronaut_docker_maven:latest

This command maps port 9090 of the container to port 9090 of our host machine, allowing us to access the application locally via http://localhost:9090.

If the container starts successfully, we should see logs indicating that our application is running. To verify our container is active, we should run:

docker ps

This displays a list of running containers, including their IDs, status, and port mappings. We’ll look for any entry with the name micronaut_docker_gradle or micronaut_docker_maven to get more information.

If we need to do some debugging, we can use the command:

docker logs <container_id>

Running the container ensures our Micronaut application is now fully deployed and operational in a Dockerized environment.

7. Conclusion

In this article, we walked through the process of building and running a Micronaut application in a Docker container. We started by setting up the Micronaut project using the CLI and Micronaut Launch, then explored how to configure Gradle and Maven to automate Docker image creation. We also demonstrated how to customize the Docker image to suit specific requirements, including modifying the base image, exposed ports, and naming conventions. Finally, we built and ran the Docker container, ensuring the application was accessible and fully operational.

By combining the flexibility of Micronaut with the portability of Docker, we can streamline the development and deployment of scalable, lightweight applications. This integration not only simplifies workflows but also ensures consistency across environments, making it an invaluable approach for modern microservice development.

We can find a complete implementation of this tutorial over on GitHub.