Using Multiple Repositories on Maven Project

3 min readDec 29, 2023

Apache Maven is a software project management used on Java projects as package management.

You may face situations requiring configuring multiple repositories on your project, for example, if you have a custom artifact hosted on a private repo or have plugins not hosted on Maven Public Central.

In this article, I will show you two cases of adding a repository on Maven.

First case: adding a custom repo.

Second case: custom repo with other pubic repo using a proxy.

Understanding Maven Repositories

There are two types of repositories in Maven: local and remote.

Local Repository

This repo is stored on the machine in path ~/.m2/repository, which is a cache of downloaded artifacts.

Remote Repository

The default remote repository is Maven Central, which hosts most artifacts and open-source libraries and plugins.

Configuring Custom Repository

The first thing you should do is, to add your repo in the pom.xml file, and to do that add the <repositories> element within the <project> element to define the repositories your project will use in pom.xml. For example:

<project>
    <!-- Other configurations -->

    <repositories>
        <repository>
            <id>custom-repo</id>
            <url>https://example.com/maven-repo</url>
        </repository>
        <!-- Add more repositories as needed -->
    </repositories>

    <!-- Other configurations -->
</project>

In this example, a custom repository with the ID custom-repo and URL https://example.com/maven-repo is added. You can include additional <repository> elements for each repository you want to use and the ID of the repository should be unique.

Now with this config, the maven will start downloading the dependency from maven central, and if not found it will start locking for in the custom repo.

If your custom repo does not enable SSL and is using HTTP protocol you will face an error while downloading your custom artifact, an example of an error message:

from/to maven-default-http-blocker (http://0.0.0.0/): Blocked mirror for repositories: [internal-repository (http://192.168.1.24:8081/repository/, default, releases+snapshots)]

the error message means the repo is blocked since is not secure, to solve this issue, you will have to add the repo as Mirror in the settings.xml file.

Create a settings.xml file in your project directory and add the below content:

<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">

    <!-- Other settings may go here -->
    
    <mirrors>
        <mirror>
            <id>insecure-repo</id>
            <mirrorOf>external:http:*</mirrorOf>
            <url> {Your Repo URL} </url>
            <blocked>false</blocked>
        </mirror> 
    </mirrors>

    
</settings>

Now, you have to use the settings.xml file with every maven command, for example, if you want to build you can write the below

mvn install -s settings.xml

Configuring Multibe Repositoies

Having multiple repositories is something common, for example, you are not using the pubic Maven Central to download public packages or dependencies, and you are using something like a Nexus Proxy to download the public dependencies and artifacts, in the meantime you have your private artifacts that hosted in a different repo.

In this case, the pom.xml file will define your private repo, for example,

<project>
    <!-- Other configurations -->

    <repositories>
        <repository>
            <id>custom-repo</id>
            <url>{Your Privte Repo URL}</url>
        </repository>      
    </repositories>

    <!-- Other configurations -->
</project>

and the settings.xml file will define your public repo and also your private repo again.

Below example of the settings.xml with two repos:

<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">

    <!-- Other settings may go here -->
    
    <mirrors>
        
        <mirror>
            <id>public-mirror</id>
            <url> {Your Public Repo URL } </url>
            <mirrorOf>central</mirrorOf>
        </mirror>

        <mirror>
            <id>privite</id>
            <url> {Your Privte Repo URL} </url>
            <mirrorOf>external:http:*</mirrorOf>              
        </mirror> 
    </mirrors>

    
</settings>

If your custom repository requires authentication, you can provide credentials in the settings.xml file under the <servers> section:

<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">

    <servers>
        <server>
            <id>central</id>
            <username>your-username</username>
            <password>your-password</password>
        </server>
        <!-- Add more server configurations as needed -->
    </servers>

    <!-- Other settings may go here -->
    
    <mirrors>
        
        <mirror>
            <id>public-mirror</id>
            <url> {Your Public Repo URL } </url>
            <mirrorOf>central</mirrorOf>
        </mirror>

        <mirror>
            <id>privite</id>
            <url> {Your Privte Repo URL} </url>
            <mirrorOf>external:http:*</mirrorOf>              
        </mirror> 
    </mirrors>

    
</settings>

Then you can start building the source code by using the settings.xml file,

mvn install -s settings.xml

Conclusion

Configuring multiple repositories in Maven allows you to leverage a variety of external dependencies for your projects. Whether you need to access private repositories, third-party libraries, or custom plugins.