Best tutorial for Maven settings file | Sample mvn settings.xml example

A maven is a build tool for Java projects. Most of the developers have used maven over ant these days because maven resolves their dependencies.

What is the maven settings.xml file?

The settings.xml file is used to configure maven execution in multiple ways. It contains the following setting configurations

  • Local and remote repositories with security enabled
  • Proxy configuration and server credentials.
  • maven profiles and active profiles
  • These settings are specific to the user where Maven is configured.

What are user and global settings XML file Location

There are two types of settings.xml based on the location of these files.

  • Global settings.xml
  • User settings.xml

Each maven project uses one of them from the user and global settings files.

The Default global settings location is ${M2_HOME}//conf//settings.xml.

M2_HOME is a maven installation location

The user settings location on your machine is ~/.m2/settings.xml. ~ represents the user’s home location directory.

what is a repository in Maven

As you know, in a java application, there are a lot of dependencies such as log4j, and Apache libraries. These are called dependencies to your project.

you have to define all your dependencies in pom.xml.

These libraries are available in apache repositories. so you have to download all these files when you want to use maven in your project.
If dependencies are configured to your project, these libraries(jar files) are downloaded to your local repository for the first to your company host.

The local repository contains java libraries downloaded from different libraries repositories.

What is a mirror in settings.xml of maven?

<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 https://maven.apache.org/xsd/settings-1.0.0.xsd">
<mirrors>
  <mirror>
    <id>Asia</id>
    <name>Asia Central</name>
    <url>http://asia.maven.org/maven2</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>

id, and name are user-friendly names of a mirror url: mirror base URL, during download repositories, It will connect to mirror URL instead of repository Url. mirror is a value, and central means maven central repository. And other values *, and external.

In the above example, if any dependencies are trying to download from a central repository, it will hit mirror url instead of maven central repo.

This enables us to stop maven from trying to access from maven central repo.

Settings.xml sample example file

settings.xml file contains the following items

  • profiles: environments like dev, test, and stage-specific profiles to configure
  • servers: configure application server details
  • Repositories: remote repository locations like maven central repo
  • plugin repositories: plugin repositories remote location
  • activeProfile: active profile to configure
  • proxies: HTTP and HTTPS proxies are to be configured here.

Here is a sample settings.xml template example

<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">
  <profiles>
    <profile>
        <repositories>
        <repository>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
         </pluginRepository>
      </pluginRepositories>
</profile>
</profiles>

<server>
        <id>Websphere</id>
        <username>username</username>
        <password>password</password>
    </server>
  <proxies>
    <proxy>
      <id>userspecificproxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.com</host>
      <port>8080</port>
      <username>usernameofproxy</username>
      <password>passwordofproxy</password>
      <nonProxyHosts>configure here</nonProxyHosts>
    </proxy>
  </proxies>
    <activeProfiles>
    <activeProfile>env-dev</activeProfile>
  </activeProfiles>

</settings>

How to find which settings.xml file is used?

We can configure settings.xml in global and local locations.

How to determine which settings.xml file is used in the application

There is no direct maven command to find settings.xml being a user.

We can find the location If you enable debugging logs during the mvn command.

mvn clean -X

And output:

[DEBUG] Reading global settings from A:\Java\apache-maven-3.3.9\bin\..\conf\settings.xml
[DEBUG] Reading user settings from C:\Users\Kiran\.m2\settings.xml
[DEBUG] Reading global toolchains from A:\Java\apache-maven-3.3.9\bin\..\conf\toolchains.xml
[DEBUG] Reading user toolchains from C:\Users\Kiran\.m2\toolchains.xml
[DEBUG] Using local repository at C:\Users\Kiran\.m2\repository
[DEBUG] Using manager EnhancedLocalRepositoryManager with priority 10.0 for C:\Users\Kiran\.m2\repository

It will give global settings and user settings location file details.

How to read the maven settings file in java projects?

There is maven command help:effective-settings to get settings xml content

mvn help:effective-settings

This command solves some of the problems

  • how to get maven local repository location
  • how to find the maven central repository location
Effective user-specific configuration settings:

<?xml version="1.0" encoding="Cp1252"?>
<!-- ====================================================================== -->
<!--                                                                        -->
<!-- Generated by Maven Help Plugin on 2021-06-15T15:12:25+05:30            -->
<!-- See: http://maven.apache.org/plugins/maven-help-plugin/                -->
<!--                                                                        -->
<!-- ====================================================================== -->
<!-- ====================================================================== -->
<!--                                                                        -->
<!-- Effective Settings for 'Kiran' on 'Kiran'                              -->
<!--                                                                        -->
<!-- ====================================================================== -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <localRepository>C:\Users\Kiran\.m2\repository</localRepository>
  <pluginGroups>
    <pluginGroup>org.apache.maven.plugins</pluginGroup>
    <pluginGroup>org.codehaus.mojo</pluginGroup>
  </pluginGroups>
</settings>


[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 35.076 s
[INFO] Finished at: 2021-06-15T15:12:25+05:30
[INFO] Final Memory: 17M/207M
[INFO] ------------------------------------------------------------------------

How to configure Proxy settings in settings.xml maven application

settings.xml contains a proxies tag to configure multiple proxy configurations.

Here is a sample settings.xml example for configuring HTTP and HTTPS proxies. This contains a protocol, username and password, and host details

<proxies>
  <!-- Http Proxy setting configuration-->
  <proxy>
    <id>optional</id>
    <active>true</active>
    <protocol>http</protocol>
    <username>proxyuser</username>
    <password>proxypass</password>
    <host>proxy-hostname.com</host>
    <port>80</port>
    <nonProxyHosts>otherhosts.com</nonProxyHosts>
  </proxy>
  <!-- HTTPS Proxy configuration details -->
  <proxy>
    <id>optional</id>
    <active>true</active>
    <protocol>https</protocol>
    <username>username</username>
    <password>password</password>
    <host>proxy-hostname.com</host>
    <port>80</port>
    <nonProxyHosts>otherhosts.com</nonProxyHosts>
  </proxy>
</proxies>

How to tell maven to take specific settings.xml file

This can be achieved with the mvn command line.

You can override the user settings file via the -s option.

mvn -s c:/settings.xml

global settings can be overridden with the -gs option.

mvn -gs c://users/adming/settings.xml

This works in maven 3.6.3 or the latest versions.