How to install Maven and build apps with the mvn command line

Apache Maven forms the backbone of build tools like Gradle, continuous integration tools like Jenkins and even development tools like Eclipse. But because these aforementioned products often abstract Maven away, many developers have never had any reason to properly learn Maven fundamentals. This tutorial will help to quickly address that build tool knowledge shortcoming by demonstrating how easy it is to install Maven, create a Maven project and run a simple build job using the mvn command-line tool.

How to install Maven in general

Simply put, Maven is a command-line tool for building and managing any Java-based project.

The Maven Project provides a simple ZIP file containing a precompiled version of Maven for our convenience. There is no installer. It’s up to us to set up our prerequisites and environment to run Maven.

The installation of Apache Maven is a simple process of extracting the archive followed by configuring Maven such that the mvn executable is available in the OS classpath.

A Maven install is one of the easier software installations you can do. At a high level, the steps to install Maven are:

1. Download Maven binaries from the Apache website.
2. Unzip the Apache Maven download, and move the folder to a place on your computer where you keep all of your other DevOps tools.
3. Add system variables named MAVEN_HOME and M2_HOME, and point both of these variables to the root Maven directory. The root Maven directory will contain a folder named \bin, which contains the pivotally important mvn command-line utility.
4. The root Maven directory contains a subfolder named \bin. Add this \bin directory to the OS’ path. This makes the mvn command-line tool universally available to the OS.

Prerequisites before install Maven

Maven is written in Java. So, to run Maven, we need a system that has Java installed and configured properly. We can download an OS-compatible Java JDK from Oracle’s download site, for example.  It’s recommended to install it to a pathname without spaces.

Once Java is installed, we need to ensure that the commands from the Java JDK are in our PATH environment variable.

To do so, we will run the command below to get the currently installed version info:

java -version

Installing Maven on Windows

To install Maven on Windows, we head over to the Apache Maven site to download the latest version and select the Maven zip file, for example, apache-maven-3.8.4-bin.zip.

Then, we unzip it to the folder where we want Maven to live.

Adding Maven to the Environment Path

We add both M2_HOME and MAVEN_HOME variables to the Windows environment using system properties and point them to our Maven folder.

Then, we update the PATH variable by appending the Maven bin folder — %M2_HOME%\bin — so that we can run the Maven command everywhere.

To verify it, we run:

mvn -version

The command above should display the Maven version, the Java version, and the operating system information. That’s it. We’ve set up Maven on our Windows system.

Installing Maven on Linux

To install Maven on the Linux operating system, we download the latest version from the Apache Maven site and select the Maven binary tar.gz file, for example, apache-maven-3.8.4-bin.tar.gz.

Redhat, Ubuntu, and many other Linux distribution are using the BASH as their default shell. In the below section, we will be using bash commands.

First, let’s create a location for Maven:

$ mkdir -p /usr/local/apache-maven/apache-maven-3.8.4

Then, we extract the archive to our Maven location:

$ tar -xvf apache-maven-3.8.4-bin.tar.gz -C /usr/local/apache-maven/apache-maven-3.8.4

Adding Maven to the Environment Path

We open the command terminal and edit the .bashrc file using the below command:

$ nano ~/.bashrc

Next, let’s add Maven-specific lines to the file:

export M2_HOME=/usr/local/apache-maven/apache-maven-3.8.4 
export M2=$M2_HOME/bin 
export MAVEN_OPTS=-Xms256m -Xmx512m 
export PATH=$M2:$PATH

Once we save the file, we can reload the environment configuration without restarting:

$ source ~/.bashrc

Finally, we can verify if Maven has been added:

$ mvn -version

The output should be similar to the below:

Apache Maven 3.8.4 (81a9f75f19aa7275152c262bcea1a77223b93445; 2021-01-07T15:30:30+01:29)
Maven home: /usr/local/apache-maven/apache-maven-3.8.4

Java version: 1.8.0_75, vendor: Oracle Corporation

Java home: /usr/local/java-current/jdk1.8.0_75/jre

We have successfully installed Maven on our Linux system.

Installing Maven on Ubuntu

In a terminal, we run apt-cache search maven to get all the available Maven packages:

$ apt-cache search maven
....
libxmlbeans-maven-plugin-java-doc - Documentation for Maven XMLBeans Plugin
maven - Java software project management and comprehension tool
maven-debian-helper - Helper tools for building Debian packages with Maven
maven2 - Java software project management and comprehension tool

The Maven package always comes with the latest Apache Maven.

We run the command sudo apt-get install maven to install the latest Maven:

$ sudo apt-get install maven

This will take a few minutes to download. Once downloaded, we can run the mvn -version to verify our installation.

$ mvn -version

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 11.0.14.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-11-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "5.13.0-39-generic", arch: "amd64", family: "unix"

Installing Maven on Mac OS X

To install Maven on Mac OS X operating system, we download the latest version from the Apache Maven site and select the Maven binary tar.gz file, for example, apache-maven-3.8.4-bin.tar.gz.

Then we extract the archive to our desired location.

Adding Maven to the Environment Path

First, let’s open the terminal and switch to the directory where the files were extracted to and then log in as superuser.

Second, we need to remove the tar.gz archive:

rm Downloads/apache-maven*bin.tar.gz

Third, we have to fix the permissions and switch the Maven contents:

chown -R root:wheel Downloads/apache-maven* 
mv Downloads/apache-maven* /opt/apache-maven

Then, let’s archive the Admin session and add Maven binaries to the path and append:

exit 
nano $HOME/.profile 
export PATH=$PATH:/opt/apache-maven/bin

Finally, we use Ctrl+x to save and exit from nano.

To load the new setup, let’s run:

bash

Now, we test if Maven is installed successfully using the command below:

mvn -version

We are now ready to use Maven on our Mac OS X.

Adding Maven to the Environment Path for macOS Catalina or Higher

macOS is abandoning the Bourne-Again Shell (bash), the command interpreter for most GNU / Linux distributions, in favor of the Z shell (zsh). This shell can be thought of as an extended version of bash.

Zsh sets itself apart with its advanced command completion mechanism, typo correction, and even feature-adding module system.

In the case of macOS Catalina or a higher version where the default shell is zsh, we have to append to a different file instead:

nano ~/.zshenv  
export PATH=$PATH:/opt/apache-maven/bin

To reload the environment, we need to issue:

source ~/.zshenv 

The rest of the operations remain the same.

HighSierra Compatibility

For HighSierra, we’ll need to additionally add Maven binaries to the path and append:

nano $HOME/.bashrc
export PATH=$PATH:/opt/apache-maven/bin

We use Ctrl+x to save and exit from nano. Then we run bash to load the new setup.

Learn Maven’s key concepts

A strong understanding of Maven fundamentals is important, but being able to play the Maven game on expert level isn’t necessary either. The key Maven concepts every Java developer should be adept with include:

• How the project object model (POM) file works. This is the pom.xml file that sits at the root of every Maven project.
• The basic structure of a Maven project, and how Maven archetypes can be used to structure different types of projects, be it a a J2SE, Jakarta EE or Spring Boot app.
• The purpose of the commonly used Maven lifecycle phases and hooks, including: clean, compile, test, package, install and deploy.
• How dependencies are configured in the pom.xml file and how Maven resolves and links to external libraries at runtime.
• The role of the local Maven repository and the benefits that can be garnered through the use of a shared binary repository such as Apache Archiva, Sonatype’s Nexus repository manager or JFrog’s Artifactory.

That may sound like a tall order, but it’s actually not. Any software developer or member of the operations team could easily take a few hours on a Friday afternoon when they’re doing nothing other than pretending to work and just download Apache Maven, install the tool and configure the requisite MAVEN_HOME and M2_HOME system variables.  Then take the rest of the afternoon to play around with the mvn command tool, create a Maven project or two, run a few Maven tasks and add a logging framework dependency to a piece of code. Within an hour or two, they’d likely know more about Maven than the captain of the DevOps team.

It’s not hard to learn Maven. It is worth a developer’s time to invest a few hours into playing with the build tool and mastering the Maven fundamentals, especially if the adoption of DevOps tools like Jenkins or Gradle are on the horizon.

Learn Maven with the mvn command line

If you want to learn Maven, you need to make sure your Maven install was successful, and you can’t be completely sure of that until you have successfully invoked the mvn command-line tool. When you install Maven on Windows, check the mvn by entering the following command on the DOS prompt:

C:\>mvn --version

Create a Maven project

Maven has stringent expectations on how to structure a software project, so it’s best to ask the mvn command-line utility to create a Java project, rather than to create one by hand. To do so, just create a folder in which you want your Maven project to reside, and then, issue the following command:

mvn -B archetype:generate \
   -DarchetypeGroupId=org.apache.maven.archetypes \
     -DgroupId=com.mcnz.maven \
       -DartifactId=install-maven-tutorial

Note how the above instruction is broken over four lines due to formatting constraints, but when executed in a scripting environment, it should all be contained on a single line, lest you will receive a Failed to execute goal error.

This command instructs the tool to create a Maven project named install-maven-tutorials (the artifactId). This command also indicates that all Java code will be placed under a set of subfolders that map to the package name com.mcnz.maven (the groupId). The command itself might look a little bit intimidating, but quite frankly, this command is probably the most difficult task for people who want to learn how to install and use Maven. Furthermore, when you look at the structure of the Maven project this command creates, the switches and flags used in the mvn command will make much more sense.

Maven directory structure

Maven can create a variety of different projects, from a microservice to a Spring Boot application, depending upon what type of Maven archetype you specify. The command used in this Maven tutorial simply uses a default Maven archetype, which maps to a basic Java project.

In my personal development environment, I ran this Maven command from a folder named _maven projects. The command then created a new Maven project folder named install-maven-tutorial, based on the -DartifactId switch. Maven also created an impressive branch of folders under the project for separating test code from application source code. The default Maven directory structure looks as follows:

install-maven-tutorial
|--pom.xml
~--src
----main
~------java
~--------com
----------mcnz
~------------mvn
|--------------App.java

~----test
~------java
~--------com
~----------mcnz
~------------mvn
|--------------AppTest.java

Along with the impressive directory structure, the Maven command also created three additional files:

1. pom.xml
2. App.java
3. AppTest.java

A Maven POM example

A key objective when you learn Maven is to understand the role of the pom.xml file. The POM (Project Object Model) file describes how to build a given project, how the code should be packaged when it is deployed and any dependencies upon which the project relies.

When you look at the pom.xml file that was generated when the Maven project was created, you will notice it contains the artifactId and groupId properties that were specified when you ran the mvn command-line utility. In addition, Maven has indicated through the version property that this is a snapshot version. You can use the packaging property to package and deploy the project as a JAR file. You can also see from the dependency management section that you will use the JUnit during the test lifecycle phase.

Here’s the Maven POM example file generated when you execute the task to create a new Maven project.

<project>
  <!--Install and learn Maven tutorial-->
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mcnz.maven</groupId>
  <artifactId>install-maven-tutorial</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>install-maven-tutorial</name>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

</project>

Sample Maven Java files

Along with the pom.xml file, Maven provides two Java classes named App.java and AppTest.java to help get your project started. The App.java file simply contains a basic Hello World application.

package com.mcnz.maven;

/* App.java from the install Maven tutorial.*/

public class App {
    public static void main( String[] args ){
        System.out.println( "Hello World!" );
    }
}

The App.Test.java file simply contains a simple JUnit test that will always pass.

package com.mcnz.maven;
import junit.framework.*;

/* AppTest.java from the install Maven tutorial.*/

public class AppTest extends TestCase{

    public void testApp(){
        assertTrue( true );
    }

}

Run a Maven build job

These two Java files aren’t particularly interesting, but they do allow you to test some key Maven build facilities, such as compiling code, running tests and packaging an application. Run the following command from the root folder of the project. It will compile the code in the App.java file, run the JUnit test in the AppTest.java file and zip and package the compiled code in a JAR file.

C:\_maven projects\install-maven-tutorial>mvn compile test package

You may see the compilation errors:

[ERROR] COMPILATION ERROR : 
[INFO] -------------------------------------------------------------
[ERROR] Source option 5 is no longer supported. Use 6 or later.
[ERROR] Target option 1.5 is no longer supported. Use 1.6 or later.

This is a message from a newer javac, e.g.:

$ java -version
openjdk version "11" 2018-09-25

$ javac -source 1.5 -target 1.5 Test.java
error: Source option 5 is no longer supported. Use 6 or later.
error: Target option 1.5 is no longer supported. Use 1.6 or later.

I fixed this by adding this in pom.xml file:

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> 
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <failOnMissingWebXml>false</failOnMissingWebXml>
</properties>

Package apps with the mvn command

As the mvn command-line utility runs, Maven will display the results of compilation, communicate the results of any failed JUnit test and specify the location of the packaged application. In this instance, the mvn command has created a new folder in the project named target and added a file to that folder with the following name: install-maven-tutorial-1.0-SNAPSHOT.jar.

Use the mvn command line to learn Maven

And that’s all there is to it if you need to know how to install Maven and are interested in performing a simple build using the mvn command-line utility. It’s really not that hard to learn Maven. Of course, there wasn’t a great deal of Java development in this exercise, but with the Maven directory structure created, the pom.xml file added to the root of the project and sample source code provided, that can be addressed when the developer begins to write code. The process will be much easier to do with Maven taking care of the testing, compiling and packaging.

Where is the Maven Local Repository?

This quick writeup will focus on where Maven stores all the local dependencies locally – which is in the Maven local repository.

Simply put, when we run a Maven build, all the dependencies of our project (jars, plugin jars, other artifacts) are all stored locally for later use.

Also keep in mind that, beyond just this type of local repository, Maven does support three types of repositories:

• Local – Folder location on the local Dev machine
• Central – Repository provided by Maven community
• Remote – Organization owned custom repository

Let’s now focus on the local repository.

The Local Repository

The local repository of Maven is a directory on the local machine, where all the project artifacts are stored.

When a Maven build is executed, Maven automatically downloads all the dependency jars into the local repository.

Usually, this directory is named .m2.

Here’s where the default local repository is located based on OS:

Windows: C:\Users\\.m2

Linux: /home//.m2

Mac: /Users//.m2

And of course, for Linux and Mac, we can write in the short form:

~/.m2

Custom Local Repository in settings.xml

If the repo is not present in this default location, it’s likely because of some pre-existing configuration.

That config file is located in the Maven installation directory – in a folder called conf – and is named settings.xml.

Here’s the relevant configuration that determines the location of our missing local repo:

    C:/maven_repository
    ...

That’s essentially how we can change the location of the local repo – and of course, if that location is changed, we’ll no longer find the repo at the default location.

The files stored in the earlier location will not be moved automatically.

Passing Local Repository Location via Command Line

Apart from setting the custom local repository in Maven’s settings.xml, the mvn command supports the maven.repo.local property, which allows us to pass the local repository location as a command-line parameter:

mvn -Dmaven.repo.local=/my/local/repository/path clean install

In this way, we don’t have to change Maven’s settings.xml.

Startup Spring Boot Application

Add Maven Plugin to POM.XML

<build>
   <plugins>
     <plugin>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

Build Spring Boot Project with Maven

maven package

or

mvn install / mvn clean install

Run Spring Boot app using Maven:

mvn spring-boot:run

[optional] Run Spring Boot app with java -jar command

java -jar target/mywebserviceapp-0.0.1-SNAPSHOT.jar