Micronaut is a modern, JVM-based framework designed for building microservices and serverless applications. It’s known for its low memory footprint, fast startup time, and compile-time dependency injection, making it an ideal choice for containerized environments. Docker complements Micronaut perfectly by providing isolated, portable runtime environments that can be deployed consistently across development, testing, and production systems. Together, they create a powerful foundation for building scalable, cloud-native applications.
In this article, we will walk through the process of building a Micronaut application and running it within a Docker container.
1. Prerequisites
Before building and running a Micronaut application in Docker, ensure you have the following installed on your system:
- Java 17 or later – Micronaut requires JDK 17+.
- Maven or Gradle (for build automation).
- Micronaut CLI (optional but recommended).
- Docker – Required to build and run the application in a container.
2. Setting Up a Micronaut Application
Before we containerize the application, we need to create a simple Micronaut application. Micronaut provides a CLI tool to generate a new project with a predefined structure.
Run the following command to generate a new Micronaut application:
mn create-app com.jcg.micronautdocker --build=maven
This command uses the Micronaut CLI (mn) to generate a new Micronaut application with the following configurations:
create-app– Creates a new Micronaut application.com.jcg.micronautdocker– Defines the package structure and project name.- This means the base package will be
com.jcg.micronautdocker. - The generated source files will be located under
src/main/java/com/jcg/micronautdocker/.
- This means the base package will be
--build=maven– Specifies that the project should use Maven as the build tool.
After running this command, a new Micronaut project is created in a directory named micronautdocker, containing a well-structured application with the necessary configuration files, dependencies, and starter code. The pom.xml file is automatically set up for Micronaut, Maven, and Java development, allowing us to build and run the application easily.
To navigate into the project directory, run:
cd micronautdocker
The generated project contains a main class in src/main/java/com/jcg/micronautdocker/Application.java, which serves as the entry point of the application.
3. Creating a Simple Micronaut Controller
To test our Micronaut application inside Docker, we will create a simple REST controller with a /hello endpoint. Modify Application.java to look like this:
package com.jcg;
import io.micronaut.runtime.Micronaut;
public class Application {
public static void main(String[] args) {
Micronaut.run(Application.class, args);
}
}
Now, create a new controller under src/main/java/com/jcg/micronautdocker/HelloController.java:
package com.jcg;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
@Controller("/hello")
public class HelloController {
@Get
public String sayHello() {
return "Hello, Micronaut with Docker!";
}
}
This controller defines a GET /hello endpoint that returns a simple message. To test the application locally before containerizing it, run:
./mvnw mn:run
Now, navigate to http://localhost:8080/hello in your browser. If everything is working, you should see the response:
4. Dockerizing the Application – Using Jib from Google Cloud Tools
Instead of manually writing a Dockerfile, we can use Jib from Google Cloud Tools to build and push our Micronaut application’s Docker image. Jib is a fast, declarative, and reproducible containerization tool that eliminates the need for docker build or docker push commands. It integrates directly into Maven, making the process much simpler.
To configure Jib in our Maven-based Micronaut project, we modify our pom.xml file to define container properties and set up the Jib Maven Plugin.
4.1 Modify the pom.xml File for Jib
We define essential Docker properties, including the base image and container image name, in the <properties> section.
<properties>
...
<docker.baseImage>eclipse-temurin:21-jre-alpine</docker.baseImage>
<docker.imageName>micronaut-app-maven</docker.imageName>
</properties>
4.2 Configure Jib in the <build> Section
Next, we configure the Jib Maven Plugin inside <build> to use the properties we defined:
<build>
<plugins>
...
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>jib-maven-plugin</artifactId>
<version>3.4.4</version>
<configuration>
<from>
<image>${docker.baseImage}</image>
</from>
<container>
<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>
The Jib configuration starts with specifying the base image, where we use eclipse-temurin:21-jre-alpine, a lightweight Java 21 runtime environment. This choice keeps the container small and efficient while ensuring compatibility with our Micronaut application. Additionally, we define the image name as micronaut-app-maven, making it easy to reference when running the container with docker run.
Within the Jib Maven plugin configuration, the <from> section specifies the base image, while the <container> section sets up the entry point, ensuring the application runs correctly using the java -cp command. Finally, the <to> section defines the target image name, ensuring consistency when building and deploying the containerized application.
5. Building and Running the Jib Container
5.1 Build the Image Using Jib
Run the following command to build the image:
mvn compile jib:dockerBuild
Jib will automatically build and package the application, create an optimized layered Docker image, and store it in the local Docker registry.
[INFO] Using base image with digest: sha256:4e9ab608d97796571b1d5bbcd1c9f430a89a5f03fe5aa6c093888ceb6756c502 [INFO] [INFO] Container entrypoint set to [sh, -c, java -cp /app/resources:/app/classes:/app/libs/* com.jcg.Application] [INFO] [INFO] Built image to Docker daemon as micronaut-app-maven [INFO] Executing tasks: [INFO] [==============================] 100.0% complete [INFO] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
You can check the list of Docker images to confirm that micronaut-app-maven has been created.
docker images
After running the docker images command, the output will display a list of locally available Docker images. For example, the output might look like this:
REPOSITORY TAG IMAGE ID CREATED SIZE micronaut-app-maven latest 99072098b81f 55 years ago 216MB
This confirms that the micronaut_app_maven image has been successfully built and is available for running in a container.
5.2 Run the Container
After successfully building the Docker image, the next step is to run the container and ensure the Micronaut application starts correctly inside it. Use the following run the Micronaut application inside a container:
docker run -p 8282:8080 micronaut-app-maven:latest
Docker will start a new container from the micronaut-app-maven image, binding port 8080 of the container to port 8282 on the host machine. The expected output in the terminal will look similar to this:
The log message INFO io.micronaut.runtime.Micronaut - Startup completed in 60426ms indicates that the application has successfully booted up, though the startup time may vary depending on system resources. The message Server Running: http://0983f74ff65d:8080 confirms that the application is listening on port 8080 inside the container. Since we specified -p 8282:8080, this port is mapped to the host machine, allowing us to access the Micronaut application from the host system.
To check if our container is active, we should run the following command:
docker container ls -a
The docker container ls -a command lists all running containers along with important details. If the Micronaut container is running, it will appear in the output. The output will look something like this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7806d6a1cf0b micronaut-app-maven "sh -c 'java -cp /ap…" 14 minutes ago Up 14 minutes modest_ritchie
To confirm that the application is working, open a web browser and go to http://localhost:8282/hello. The response should return the expected output, such as:
This confirms that the Micronaut application is running successfully inside a Docker container and is accessible from the host system.
6. Conclusion
In this article, we explored how to build, containerize, and run a Java Micronaut application using Docker. We started by generating a Micronaut project with Maven and demonstrated an alternative approach using Jib from Google Cloud Tools, which simplifies the process by eliminating the need for a Dockerfile. Finally, we covered how to build and run the application inside a Docker container, verify its status, and access it from the host machine. By leveraging Micronaut and Docker, we can create lightweight, cloud-native applications that are easy to deploy and scale.
7. Download the Source Code
This was an article about using Docker to containerize a Java Micronaut application.
You can download the full source code of this example here: java micronaut docker
