Maven | Holy Grail

What is Maven?

Apache Maven is a build automation tool used primarily for Java projects. Maven can also be used to build and manage projects written in C#, Ruby, Scala, and other languages.

Maven addresses two aspects of building software: how software is built, and its dependencies. It uses a Project Object Model (POM) file to describe the project configuration.

Prerequisites

SDKMAN! foundation Java languages

Installation

When installing with SDKMAN!, it is not required to set the M2_HOME environment variable or add Maven to the PATH in your ~/.zshrc or ~/.bashrc config file.

Open a new terminal session:

sdk install maven

Close your terminal session.

Verify Your Installation

Open a new terminal session:

mvn -version

You should see output similar to:

Apache Maven <maven-version>
Maven home: <maven-home>
Java version: <java-version>, vendor: <java-vendor>

Output will vary based on your installed Maven and Java versions.

Good to Know

Find Maven Installation

Maven installed via SDKMAN! is located at:

~/.sdkman/candidates/maven/current

Find settings.xml Configuration

The Maven settings file is located at:

~/.m2/settings.xml

This file is used to configure:

Repository mirrors
Proxy settings
Server credentials
Build profiles

Common Maven Commands

# Clean build artifacts
mvn clean

# Compile the project
mvn compile

# Run tests
mvn test

# Package the project (create JAR/WAR)
mvn package

# Install to local repository
mvn install

# Clean and package in one command
mvn clean package

# Skip tests during build
mvn package -DskipTests

Switch Maven Versions

# List available versions
sdk list maven

# Install a specific version
sdk install maven <version>

# Use a specific version
sdk use maven <version>

# Set default version
sdk default maven <version>

For more details on SDK version management, refer to the SDKMAN! foundation guide.

Troubleshooting

JAVA_HOME not set

If Maven complains about JAVA_HOME:

# Check if JAVA_HOME is set
echo $JAVA_HOME

# If using SDKMAN! for Java, it should be set automatically
# Verify with:
sdk current java

Out of memory errors

For large projects, increase Maven’s heap size:

export MAVEN_OPTS="-Xmx2048m"

Add this to your ~/.zshrc to make it permanent.

Dependency resolution failures

First, try removing only the specific problematic artifact:

rm -rf ~/.m2/repository/com/example/problematic-artifact
mvn clean install

If that doesn’t resolve the issue, as a last resort you can clear the entire local repository cache. This will force Maven to re-download all dependencies:

rm -rf ~/.m2/repository
mvn clean install

SSL certificate issues

If you encounter SSL errors when downloading dependencies, first download and import the repository’s certificate into your JVM keystore:

# Download the certificate from the repository host
openssl s_client -connect repo.example.com:443 </dev/null 2>/dev/null | openssl x509 -outform PEM > repo-cert.pem

# Import the certificate into the JVM keystore (requires elevated privileges)
sudo keytool -import -alias repo-cert -keystore "$JAVA_HOME/lib/security/cacerts" -file repo-cert.pem -storepass changeit -noprompt

Writing to the JVM keystore at $JAVA_HOME/lib/security/cacerts typically requires elevated privileges. If you see a “permission denied” error, ensure you prefix the keytool command with sudo.

Replace repo.example.com with the actual repository hostname from the error message.

As a last-resort debugging option, you can bypass SSL verification:

mvn clean install -Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true

“For debugging only — do not use in production. Fix the underlying certificate issue.”

Resources

🔗

Maven Documentation maven.apache.org

Official Apache Maven guides and reference documentation

🔗

POM Reference maven.apache.org

Complete reference for the Project Object Model (POM) file