How to Build Multi-Module Maven Projects in Docker

1. Overview

In this tutorial, we’ll learn how to efficiently build Docker images for multi-module Maven projects. We’ll start by exploring multi-stage Docker builds to leverage Docker’s caching mechanism to its fullest.

Then, we’ll look at an alternative approach using Google’s Jib Maven plugin. This tool allows us to create optimized Docker images without the need for a Dockerfile or a Docker daemon.

2. Multi-Module Maven Project

A multi-module Maven application consists of separate modules for different functionalities. Maven builds the application by managing dependencies and assembling these modules into a single deployable unit.

For the code examples in this article, we’ll use a basic Spring Boot project with two Maven modules – representing the domain and API of our application. Let’s visualize the structure of this Maven project:

+-- parent
   +-- api
   |   `-- src
   |   `-- pom.xml
   +-- domain
   |   `-- src
   |   `-- pom.xml
    `-- pom.xml

If we take a look at the parent module’s pom.xml file, we can expect it to extend spring-boot-starter-parent and include the domain and api modules:

<project>
    <groupId>com.baeldung.docker-multi-module-maven</groupId>
    <artifactId>parent</artifactId>
    <packaging>pom</packaging>
    <version>0.0.1-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.2</version>
        <relativePath />
    </parent>
    <modules>
        <module>api</module>
        <module>domain</module>
    </modules>
    <!--  other configuration  -->
</project>

Moreover, we’ll follow the clean architecture principles, ensuring all the source code dependencies are pointing in the correct direction. Simply put, we’ll make sure that the api module depends on the domain module, and not the other way around.

3. Multi-Stage Docker Build

Multi-stage builds in Docker allow us to use multiple FROM instructions in a single Dockerfile to create smaller, more efficient images. Each stage can be used for different purposes, like compiling code or packaging an application, and only the final stage is included in the final image.

For instance, our example can use three stages: pulling the dependencies, building the application, and preparing the runtime environment. Let’s create our Dockerfile with these three distinct sections:

# pre-fetch dependencies
FROM maven:3.8.5-openjdk-17 AS DEPENDENCIES
# build the jar
FROM maven:3.8.5-openjdk-17 AS BUILDER
# prepeare runtime env
FROM openjdk:17-slim

3.1. Pre-Fetching Dependencies

The DEPENDENCIES stage will pre-fetch and cache Maven dependencies for our application. Let’s start by choosing our preferred maven image, and copy the three pom.xml files:

FROM maven:3.8.5-openjdk-17 AS DEPENDENCIES
WORKDIR /opt/app
COPY api/pom.xml api/pom.xml
COPY domain/pom.xml domain/pom.xml
COPY pom.xml .

After that, we need to use the maven-dependency-plugin and its go-offline goal to resolve and download all dependencies specified in our pom.xml files. Additionally, we’ll run the command in a non-interactive mode by specifying the “-B” option, and prompt all the errors via “-e”:

RUN mvn -B -e org.apache.maven.plugins:maven-dependency-plugin:3.1.2:go-offline -DexcludeArtifactIds=domain

Lastly, we added the excludeArtifactIds property to prevent Maven from downloading specific artifacts. In this case, it excludes the domain artifact. As a result, the domain JAR will be built locally rather than fetched from a repository.

This command ensures that when we run the build process in the next stage, all dependencies will be available locally and won’t need to be downloaded again.

3.2. Building the Image

To build the image, we first need to ensure that all required dependencies are pre-fetched and the source code is available. In the BUILDER stage, we begin by copying the necessary resources from the DEPENDENCIES stage:

FROM maven:3.8.5-openjdk-17 AS BUILDER
WORKDIR /opt/app
COPY --from=DEPENDENCIES /root/.m2 /root/.m2
COPY --from=DEPENDENCIES /opt/app/ /opt/app
COPY api/src /opt/app/api/src
COPY domain/src /opt/app/domain/src

Next, let’s run mvn clean install to compile the code and build the domain and api JAR files. Since the tests have presumably been run earlier, we can use -DskipTests to speed up the build process:

RUN mvn -B -e clean install -DskipTests

3.3. Preparing the Runtime Environment

In the final stage of our Dockerfile, we’ll set up the minimal runtime environment for our application. We’ll select the base image that the application will run on, copy the JAR file from the previous stage, and define the entry point to launch it:

FROM openjdk:17-slim
WORKDIR /opt/app
COPY --from=BUILDER /opt/app/api/target/*.jar /app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

3.4. Running the Application

Finally, we can build and run the image. Let’s also add the from-dockerfile tag to differentiate this image:

docker build -t baeldung-demo:from-dockerfile .
docker run -p 8080:8080 baeldung-demo:from-dockerfile

Needless to say, if we send a GET request to localhost:8080/api/countries, we’ll notice that our application is up and running.

As we can see, the multi-stage Dockerfile simplifies dependency management by isolating build dependencies from the final runtime environment. Additionally, it helps us reduce the final image size by copying only the necessary artifacts from build stages, improving efficiency and security.

4. Building the Project Using Jib

We can also build the Docker image using a dedicated tool such as Jib. The Jib Maven plugin is a tool that builds optimized Docker images for Java applications directly from our Maven build, without requiring a Dockerfile or Docker daemon.

Jib requires us to configure a few key properties:

• the Java base image
• the name of the resulting Docker image
• the entry point to our application
• the exposed ports

Let’s add the maven-jib-plugin to the pom.xml of our API module:

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>jib-maven-plugin</artifactId>
    <version>3.4.0</version>
    <configuration>
        <from>
            <image>openjdk:17-slim</image>
        </from>
        <to>
            <image>baeldung-demo:from-jib</image>
        </to>
        <container>
            <mainClass>com.baeldung.api.Application</mainClass>
            <ports>
                <port>8080</port>
            </ports>
        </container>
    </configuration>
</plugin>

After that, we can use Maven to build the image:

mvn compile jib:dockerBuild

As a result, Jib builds the Docker image and we can now run the application with the docker run command:

docker run -p 8080:8080 baeldung-demo:from-jib

5. Conclusion

In this article, we learned how to build Docker images for Maven projects with multiple modules. Initially, we manually created a Dockerfile where we copied all the pom.xml files, resolved all the dependencies, and built the image. Additionally, we used Docker’s multi-stage feature to take full advantage of its caching mechanism.

After that, we explored the Jib Maven plugin and used it to build the Docker image without needing a Dockerfile. The Jib plugin managed dependencies efficiently and built the image without the overhead of manually defining each build step.

As always, the complete code used in this article is available over on GitHub.