Maven Tutorial for DevOps: From Basics to Production

This chapter provides a comprehensive guide to Apache Maven from a DevOps perspective. We explore the foundational differences between compiled and interpreted languages, unpack the core mechanics of build tools, and dissect the anatomy of Maven’s single source of truth: the pom.xml. Finally, we walk through setting up a production-grade repository architecture and automating a complete Maven-to-Docker build pipeline within Jenkins.

1. Compiled vs. Interpreted Languages: The Foundation of Build Tools

To understand why build tools exist, we must first understand how different programming languages execute on a host operating system. At a high level, programming languages are categorized as either compiled or interpreted.

Compiled Languages

Compiled languages require a translation step before execution. The human-readable source code must be converted into a machine-readable format. This target format falls into two categories:

• Machine Code (CPU Native): Languages like C, C++, and Go compile directly into binary executables tailored to a specific CPU architecture. These binaries run directly on the host operating system with minimal external runtime dependencies.
• Bytecode (Runtime Native): Languages like Java, Kotlin, Scala, and Groovy compile into intermediate bytecode. This bytecode is platform-independent but requires a specialized runtime environment—the Java Virtual Machine (JVM)—to execute on the host OS.

Because compiled languages require this translation step, they always require a build stage and a dedicated build tool to invoke the compiler (e.g., javac for Java).

Interpreted Languages

Interpreted languages (such as Python or JavaScript) do not compile source code into a binary beforehand. Instead, an interpreter reads and executes the code line-by-line at runtime.

• Code Visibility: To run or deploy an interpreted application (e.g., an AWS Lambda function written in Python), you must ship the actual human-readable source code. There is no compiled binary to hide the source logic.
• Build Stage Relevance: While interpreted languages do not require a compilation step, they still benefit from a build stage to handle dependency management, linting, and packaging.

2. The Core Mission of Build Tools: Beyond Simple Compilation

A common misconception is that build tools only invoke compilers. In modern DevOps pipelines, build tools act as orchestrators for the entire software delivery lifecycle.

Key Responsibilities of a Build Tool

1. Dependency Management: Modern applications rely heavily on external libraries. If a banking application needs to calculate interest rates, developers do not write a calculator from scratch; they import a trusted library. The build tool automatically fetches this library.
2. Transitive Dependency Resolution: If your application depends on Library A, but Library A depends on Library B, and Library B depends on Library C, the build tool resolves this entire chain automatically.
3. Version Locking: To ensure reproducible builds across different environments (Developer Laptop $\rightarrow$ Jenkins CI $\rightarrow$ Production), build tools lock down the exact versions of all dependencies.
4. Testing and Quality Gates: Build tools execute unit tests, integration tests, code linters, and security scanners (such as Static Application Security Testing, or SAST).
5. Packaging and Publishing: The build tool packages the compiled code into standard formats (such as .jar for standalone Java apps, .war for web apps, or .ear for enterprise systems) and publishes them to an artifact repository.

What is an Artifact? An artifact is any deployable or reusable file generated as the output of a build process. Examples include .jar files, .war files, and compiled Docker container images.

Typical Build Automation Workflow

3. What is Apache Maven? Conventions over Configuration

Apache Maven is a build automation and project management tool designed primarily for the JVM ecosystem (Java, Kotlin, Scala, Groovy).

The Core Philosophy: Convention over Configuration

Before Maven, tools like Apache Ant required developers to manually write every build step, define where source files lived, and specify where compiled outputs should go. This resulted in massive, fragile, and non-standard build scripts.

Maven solved this by introducing Convention over Configuration. Maven defines a strict, standard project structure. If you adhere to this structure, you do not need to write configuration code telling Maven where to find your files.

By following this layout:

• Maven automatically knows that production source code is in src/main/java.
• Maven automatically knows that test code is in src/test/java.
• Maven automatically outputs all compiled classes and packaged jars to a dynamically created target/ directory.

Market Share: Maven vs. Gradle

While Apache Ant is legacy, modern JVM development is split between Maven and Gradle.

• Maven (60% - 70% of enterprise Java projects): Highly structured, XML-based, and strictly follows conventions.
• Gradle (30% - 40% of enterprise Java projects): Highly flexible, uses a Groovy/Kotlin-based DSL, and is the standard build tool for Android development.

4. Hands-On: Installing Java JDK and Maven on Linux

To understand how Maven operates under the hood, we will install it manually on an Ubuntu EC2 instance using a binary distribution. This approach gives us full control over the tool's lifecycle.

Step 1: Install the Java Development Kit (JDK)

Maven requires a Java runtime to execute and a Java compiler to build applications. We must install the JDK (Java Development Kit), which includes the compiler (javac), rather than just the JRE (Java Runtime Environment), which only runs pre-compiled bytecode.

# Update package index
sudo apt update

# Search for available OpenJDK 17 packages
sudo apt search openjdk-17

# Install OpenJDK 17 JDK
sudo apt install -y openjdk-17-jdk

# Verify installations
java -version
javac -version

Step 2: Download and Install Maven via Binary

While you can install Maven via sudo apt install maven, using the official Apache binary allows you to manage upgrades, rollbacks, and directory structures manually. This is a common practice in production environments.

# Navigate to the optional packages directory
cd /opt

# Download the Maven binary tarball
sudo wget https://dlcdn.apache.org/maven/maven-3/3.9.11/binaries/apache-maven-3.9.11-bin.tar.gz

# Extract the archive
sudo tar -xzvf apache-maven-3.9.11-bin.tar.gz

# Clean up the downloaded tarball
sudo rm -rf apache-maven-3.9.11-bin.tar.gz

# Rename the directory for simplicity
sudo mv apache-maven-3.9.11 maven

Step 3: Configure Environment Variables

To run the mvn command from any directory without specifying its full path (/opt/maven/bin/mvn), we must append its binary location to the system PATH variable.

# Open the user's bash configuration file
vim ~/.bashrc

Scroll to the bottom of the file and append the following lines:

# Export Maven Binaries to PATH
export PATH=$PATH:/opt/maven/bin

Save and exit (Esc, :wq), then reload the configuration:

# Source the bashrc to apply changes immediately
source ~/.bashrc

# Verify that the shell locates the maven binary
which mvn

# Verify Maven installation and its linked JDK
mvn -version

5. Anatomy of pom.xml: The Single Source of Truth

The Project Object Model (pom.xml) is the declarative XML file that manages a Maven project. It defines the project's identity, dependencies, properties, and build configurations.

XML Basics for DevOps Engineers

XML (Extensible Markup Language) structures data using nested tags.

• Elements: Defined by a starting tag (e.g., <project>) and a closing tag (e.g., </project>).
• Attributes: Key-value pairs defined inside a starting tag (e.g., <project xmlns="http://maven.apache.org/POM/4.0.0">).
• Parent-Child Relationships: Indented tags nested inside other tags represent hierarchical data.

The GAV Coordinates

Every Maven project and dependency is uniquely identified globally by three coordinates: Group ID, Artifact ID, and Version (GAV).

<groupId>com.cloudwithvarosh</groupId>
<artifactId>payment-service</artifactId>
<version>1.0.0-SNAPSHOT</version>

• groupId: Represents the organization or group. It typically follows the reverse domain name system (DNS) pattern (e.g., com.company.app).
• artifactId: Represents the specific module or microservice name (e.g., payment-service).
• version: Represents the current development version.
  • SNAPSHOT: Indicates an active development version (mutable). Every time you build, Maven checks for updates based on the repository's updatePolicy.
  • RELEASE: Indicates a finalized, immutable production-ready version. Once published, a release version must never be overwritten.

A Production-Grade pom.xml Template

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    <modelVersion>4.0.0</modelVersion>

    <!-- GAV Coordinates -->
    <groupId>com.cloudwithvarosh</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>My Application</name>
    <url>https://github.com/cloudwithvarosh/my-app</url>

    <!-- Properties: Centralized Version Management -->
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <spring.boot.version>3.3.4</spring.boot.version>
        <junit.version>5.11.0</junit.version>
    </properties>

    <!-- Dependency Management (Version Rulebook) -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring.boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- Active Dependencies -->
    <dependencies>
        <!-- Spring Boot Starter Web (Version inherited from dependencyManagement) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- JUnit Jupiter for Testing -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- Build and Plugin Configurations -->
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.13.0</version>
                    <configuration>
                        <source>17</source>
                        <target>17</target>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

6. Deep Dive: Dependency Management, BOMs, and Scopes

Managing dependencies efficiently is critical to keeping build times fast and security risks low.

dependencies vs. dependencyManagement

• <dependencies>: This block defines the libraries that Maven will actually download and package into your application.
• <dependencyManagement>: This block acts as a version rulebook. It does not download any libraries. Instead, it declares the versions of libraries that should be used if they are declared in the <dependencies> block. This is highly useful in multi-module projects to ensure all sub-modules use identical versions of shared libraries.

Bill of Materials (BOM)

A BOM (Bill of Materials) is a special type of pom.xml file that groups compatible versions of related libraries together.

• The Problem: Spring Boot or JUnit consists of dozens of separate libraries. If you import them individually with mismatched versions, your application will crash at runtime.
• The Solution: Import the BOM (e.g., spring-boot-dependencies) inside the <dependencyManagement> block using the <scope>import</scope> and <type>pom</type> tags. Once imported, you can declare any Spring Boot dependency in your active <dependencies> block without specifying a version tag. Maven will automatically resolve the correct, compatible version from the BOM.

DevOps Note: BOM vs. SBOM Do not confuse a Maven BOM with an SBOM (Software Bill of Materials).

• A Maven BOM is a build-time configuration file used to align dependency versions.
• An SBOM is a security document (e.g., CycloneDX or SPDX format) generated after a build to list all licenses, libraries, and vulnerabilities inside your final container image or artifact.

Dependency Scopes

Dependency scopes restrict when a library is available on the classpath. This reduces the final artifact size and limits the security attack surface.

7. Maven Lifecycles, Phases, Plugins, and Goals

Maven operates on a highly structured execution model. To run a build, you trigger a specific lifecycle phase.

The Three Built-In Lifecycles

1. default: Handles project validation, compilation, testing, packaging, and deployment.
2. clean: Handles project cleanup by deleting the target/ directory containing previous build outputs.
3. site: Generates HTML documentation and reports for the project.

Phases vs. Goals

• Phase: A logical step in a lifecycle. Phases do not perform any actual work; they are merely placeholders.
• Plugin: A collection of executable tasks.
• Goal: A specific task executed by a plugin (e.g., compiler:compile or surefire:test).

When you run a phase, Maven looks at the plugins bound to that phase and executes their corresponding goals.

The Sequential Execution Rule

Executing any phase automatically runs all preceding phases in that lifecycle.

For example, the simplified default lifecycle sequence is:

• If you run mvn compile, Maven will first run validate.
• If you run mvn test, Maven will run validate, compile, and then test.
• If you run mvn install, Maven will run every phase from validate up to install.

Direct Goal Execution

You can bypass the sequential phase execution by calling a plugin goal directly.

• mvn compile (Phase): Runs all preceding phases, including resource copying and validation.
• mvn compiler:compile (Goal): Directly executes the compiler plugin's compile goal. It does not run any preceding phases. This is useful for optimizing CI/CD pipeline speeds.

Key Phases Explained

• validate: Verifies that the project is correct and all necessary information is available.
• compile: Compiles the source code (src/main/java) into binary .class files in the target/classes directory.
• test: Runs unit tests using frameworks like JUnit.
• package: Takes the compiled code and packages it in its distributable format (e.g., .jar or .war).
• verify: Runs integration tests and checks quality gates.
• install: Copies the packaged artifact into your local repository (~/.m2/repository) so it can be used as a dependency in other local projects.
• deploy: Copies the final artifact to a remote repository (e.g., Nexus or Artifactory) for sharing with the wider organization.

8. Maven Repository Architecture: Local, Remote, and Company-Managed Mirrors

Maven uses a hierarchical repository architecture to resolve and store dependencies.

1. Local Repository

Located on the machine running Maven at ~/.m2/repository. It acts as a local cache. When a build runs, Maven first checks this directory. If the dependency is present, it is loaded instantly. If not, Maven fetches it from a remote repository and caches it here for future builds.

2. Remote Repositories

• Maven Central: The default public repository hosted by the Apache community. It contains millions of open-source libraries.
• Vendor Repositories: Third-party repositories hosted by software vendors (e.g., RedHat or Oracle) containing specialized libraries.
• Company-Managed Repositories (Enterprise Mirrors): Tools like Sonatype Nexus or JFrog Artifactory hosted inside an organization's private network.

Why Enterprise Mirrors are Mandatory in Production

In enterprise environments, letting build servers pull dependencies directly from the public internet is a major security and operational risk. Instead, organizations configure a Match-All Mirror (*).

1. Security Filtering: The mirror blocks malicious or vulnerable dependencies.
2. Caching & Speed: The mirror caches external dependencies locally within the company network, reducing external bandwidth and speeding up builds.
3. Offline Builds: If the public internet goes down, the build servers can still run builds using the cached dependencies in the mirror.

Configuring Mirrors and Credentials

Because pom.xml is checked into public or shared version control systems (SCM), you must never store credentials inside a pom.xml. Instead, credentials and mirror configurations are stored in the user's private settings.xml file.

The User-Specific settings.xml (~/.m2/settings.xml)

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    
    <!-- Define the Mirror (Redirects all external requests to Nexus) -->
    <mirrors>
        <mirror>
            <id>company-nexus</id>
            <mirrorOf>*</mirrorOf> <!-- Match all repositories -->
            <name>Internal Enterprise Mirror</name>
            <url>https://nexus.example.com/repository/maven-public/</url>
        </mirror>
    </mirrors>

    <!-- Store Private Credentials Securely -->
    <servers>
        <server>
            <id>company-nexus</id>
            <username>deployment-user</username>
            <password>EncryptedPasswordOrToken123!</password>
        </server>
    </servers>
</settings>

The Project pom.xml (Distribution Management)

The pom.xml only defines where to upload the final artifacts. It references the server credentials in settings.xml using matching <id> tags.

<distributionManagement>
    <repository>
        <id>company-nexus</id> <!-- Matches the server ID in settings.xml -->
        <url>https://nexus.example.com/repository/maven-releases/</url>
    </repository>
    <snapshotRepository>
        <id>company-nexus</id> <!-- Matches the server ID in settings.xml -->
        <url>https://nexus.example.com/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

9. Super POM vs. Parent POM in Enterprise Projects

To keep configurations DRY (Don't Repeat Yourself) across large enterprise codebases, Maven uses inheritance.

The Super POM

Every Maven project implicitly inherits from a base configuration file called the Super POM, which is bundled inside the Maven binary.

• It defines the default directory structures (src/main/java, target).
• It configures the default public Maven Central repository URL.
• It binds default plugins to the standard lifecycle phases.

The Parent POM

In a microservices architecture with dozens of services, configuring dependencies, plugins, and properties in every single pom.xml leads to configuration drift. A Parent POM centralizes these configurations.

                    [Parent POM]
             (Defines shared versions,
              plugins, and properties)
              /          |         \
             /           |          \
            v            v           v
     [Service A]    [Service B]   [Service C]
     (Child POM)    (Child POM)   (Child POM)

Example Child POM Inheriting from a Parent POM:

<project>
    <modelVersion>4.0.0</modelVersion>
    
    <!-- Inherit from Parent POM -->
    <parent>
        <groupId>com.cloudwithvarosh</groupId>
        <artifactId>enterprise-parent</artifactId>
        <version>2.1.0</version>
    </parent>

    <artifactId>billing-service</artifactId>
    <!-- Version is inherited from parent if omitted -->
    
    <dependencies>
        <!-- No version tag needed; inherited from Parent's dependencyManagement -->
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
        </dependency>
    </dependencies>
</project>

10. Hands-On Demo: Jenkins CI/CD Pipeline with Maven and Docker

In this hands-on demo, we will automate a complete pipeline. Jenkins will pull a Java application, use Maven to compile and package it into a .jar file, containerize it using a multi-stage Dockerfile, and run the container.

Step 1: Install Maven inside the Jenkins Container

To allow Jenkins to run Maven commands, we must install Maven inside the Jenkins controller (or agent) container.

# Access the Jenkins container as root
docker exec -it -u root jenkins bash

# Update package manager and install Maven
apt update && apt install -y maven

# Verify installation
mvn -version

# Exit the container
exit

Step 2: Create a Jenkins Freestyle Job

1. Open the Jenkins UI (typically http://localhost:8080).
2. Click New Item, name it Maven-Docker-Pipeline, select Freestyle project, and click OK.
3. Scroll down to the Build Steps section, click Add build step, and select Execute shell.

Step 3: Write the Automation Script

Paste the following script into the shell execution block. This script automates the creation of a sample project, compiles it, packages it, builds a Docker image, and runs it.

#!/bin/bash
set -e # Exit immediately if any command fails

echo "=================================================="
echo "STEP 1: Generating Maven Project Skeleton"
echo "=================================================="
# Clean up any previous builds
rm -rf my-app

# Generate a standard Maven project using the quickstart archetype
mvn archetype:generate \
    -DgroupId=com.cloudwithvarosh \
    -DartifactId=my-app \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.5 \
    -DinteractiveMode=false

# Navigate into the project directory
cd my-app

echo "=================================================="
echo "STEP 2: Compiling and Packaging Application"
echo "=================================================="
# Run clean package in batch mode (-B) to clean logs, and skip tests for speed
mvn clean package -B -DskipTests

echo "=================================================="
echo "STEP 3: Creating Multi-Stage Dockerfile"
echo "=================================================="
# We use a lightweight JRE image for runtime to minimize image size
cat <<EOF > Dockerfile
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
# Copy the compiled jar from the target directory into the container
COPY target/my-app-1.0-SNAPSHOT.jar /app/app.jar
# Run the application
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
EOF

# Create a .dockerignore file to prevent copying unneeded files
cat <<EOF > .dockerignore
target/classes/
target/maven-archiver/
src/
pom.xml
EOF

echo "=================================================="
echo "STEP 4: Building Docker Image"
echo "=================================================="
# Build the Docker image locally
docker build -t cloudwithvarosh/java-hello:local .

echo "=================================================="
echo "STEP 5: Running Containerized Application"
echo "=================================================="
# Run the container. The --rm flag deletes the container immediately after execution.
docker run --rm --name java-hello-instance cloudwithvarosh/java-hello:local

Step 4: Execute and Verify

1. Click Save on the Jenkins job configuration page.
2. Click Build Now to trigger the pipeline.
3. Open the Console Output for the build.

Expected Console Output:

Summary and Key Takeaways

• Compiled vs. Interpreted: Compiled languages require a build stage to translate source code into machine code or JVM bytecode. Interpreted languages run directly via an interpreter but still benefit from build tools for dependency management and packaging.
• Convention over Configuration: Maven eliminates complex build scripts by enforcing a standard directory structure (src/main/java, src/test/java, target).
• GAV Coordinates: Every Maven artifact is uniquely identified by its Group ID, Artifact ID, and Version.
• Snapshots vs. Releases: Snapshot versions are mutable, active development builds. Release versions are immutable, production-ready builds that must never be overwritten.
• Dependency Management: The <dependencyManagement> block acts as a centralized version rulebook but does not download dependencies. The <dependencies> block defines the active libraries that Maven will download and package.
• BOM (Bill of Materials): A BOM is a specialized POM file that defines compatible versions of related libraries, preventing version mismatch issues at runtime.
• Phases and Goals: Lifecycles consist of sequential phases (e.g., compile, test, package). Plugins do the actual work through specific goals (e.g., compiler:compile). Running a phase automatically executes all preceding phases in that lifecycle.
• Enterprise Repository Architecture: In production, a match-all mirror (*) like Sonatype Nexus or JFrog Artifactory is used to cache public dependencies and host private artifacts.
• Secure Credentials: To prevent security leaks, all private repository credentials must be stored in the user's local settings.xml file rather than the project's version-controlled pom.xml.
• Super POM vs. Parent POM: The Super POM is Maven's internal default configuration. A Parent POM is a user-defined file used to centralize configurations across multiple microservices.