Apache Maven Complete Guide: Concepts, Installation, settings.xml, and First Build

Originally published on 2010-04-14; fully revised and updated.

Apache Maven is a build and project management tool centered around the pom.xml. This guide is for developers and DevOps engineers who need a practical baseline: what Maven does, how installation works, how settings are managed, and how to create and build a first project.

Useful original resources: Maven downloads at maven.apache.org/download.html, and the original linked video at YouTube.

What Maven is and why DevOps teams use it

Maven is an Apache tool that standardizes how projects are built, tested, packaged, and published. It uses a declarative model in pom.xml so teams can share a common build process across repositories and environments.

• Defines project metadata (group, artifact, version, packaging).
• Resolves dependencies from local and remote repositories.
• Runs standard lifecycle phases such as compile, test, and package.
• Uses plugins for checks, reports, releases, and deployment workflows.

Maven philosophy: conventions over custom scripting

The original post compared Maven with Ant. That distinction is still useful: Maven emphasizes shared conventions and lifecycle phases, while Ant is task-oriented and script-driven.

How a Maven build flows

When you run a Maven goal, Maven reads the POM, resolves artifacts, and executes lifecycle phases using configured plugins.

flowchart TD
    A[Run mvn package] --> B[Read pom xml]
    B --> C[Resolve dependencies in local repository]
    C --> D{Artifacts missing}
    D -- yes --> E[Download from remote repository]
    D -- no --> F[Use local cache]
    E --> G[Execute lifecycle phases]
    F --> G
    G --> H[Run tests and package artifact]
    H --> I[Install artifact locally when requested]

Install Maven on Windows, Linux, and macOS

The original article used Maven 2.2.1 and legacy OS examples. The modern process is still the same at a high level: install a JDK, install Maven, set environment variables, and verify from the command line.

• Install a JDK (JRE alone is not enough).
• Download Maven from the official download page.
• Extract Maven to a stable path.
• Set JAVA_HOME and add Maven bin to PATH.
• Verify using mvn -version.

Example: Linux or macOS shell

export JAVA_HOME=/path/to/jdk
export M2_HOME=/opt/apache-maven
export PATH=$JAVA_HOME/bin:$M2_HOME/bin:$PATH
mvn -versionCode language: JavaScript (javascript)

Example: Windows command prompt

set JAVA_HOME=C:\Path\To\JDK
set M2_HOME=C:\Tools\apache-maven
set PATH=%JAVA_HOME%\bin;%M2_HOME%\bin;%PATH%
mvn -versionCode language: JavaScript (javascript)

Configure environment-specific behavior with settings.xml

Maven settings belong outside project source code. Typical uses include proxy setup, repository mirror configuration, and credentials for artifact download or deployment.

• Global settings: $M2_HOME/conf/settings.xml
• User settings: ${user.home}/.m2/settings.xml

<settings>
  <localRepository>/opt/maven-repo</localRepository>

  <mirrors>
    <mirror>
      <id>internal-mirror</id>
      <mirrorOf>*</mirrorOf>
      <url>https://repo.example.com/repository/maven-public/</url>
    </mirror>
  </mirrors>

  <servers>
    <server>
      <id>internal-mirror</id>
      <username>build-user</username>
      <password>${env.MAVEN_REPO_PASSWORD}</password>
    </server>
  </servers>
</settings>Code language: HTML, XML (xml)

Keep credentials out of pom.xml and out of source control; prefer environment variables or a secrets manager integrated with CI.

Create your first Maven project

The original article used archetype:create in its example. A commonly used modern pattern is archetype:generate with explicit coordinates.

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=falseCode language: JavaScript (javascript)

cd my-app
mvn test
mvn package

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>
</project>Code language: HTML, XML (xml)

Core POM identifiers to remember: groupId, artifactId, version, and packaging.

Common Maven commands at a glance

Best practices and common pitfalls

• Pin critical plugin versions in your POM for reproducible builds.
• Do not commit credentials in POM or settings files.
• Use a repository manager mirror in enterprise environments to improve control and caching.
• Use mvn dependency:tree early when debugging classpath issues.
• Keep CI and local JDK/Maven toolchains aligned to reduce environment drift.
• Treat legacy Maven tutorials carefully, especially those tied to very old Maven and OS versions.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.