Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Troubleshooting Node.js Apps
      • Node.js Behavior in Heroku
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Language Support
  • Java
  • Working with Maven
  • Using a Custom Maven Settings File

Using a Custom Maven Settings File

English — 日本語に切り替える

Last updated May 30, 2024

Table of Contents

  • Creating a custom settings file
  • Defining the MAVEN_SETTINGS_PATH config variable
  • Defining the MAVEN_SETTINGS_URL config variable
  • Using password protected repositories

A Maven settings.xml file defines values that configure Maven execution in various ways. Most commonly, it is used to define a local repository location, alternate remote repository servers, and authentication information for private repositories. In this article you’ll learn how to add a custom setting file to a Java application deployed on Heroku.

If you already have a Java application, you may use it for this example. Otherwise, create a simple application from the Getting Started with Java on Heroku article.

Creating a custom settings file

When a file named settings.xml is present in the root directory of an application, Heroku’s Java Support will automatically use it to configure Maven at compile time.

To demonstrate this, add a settings.xml file to the root directory of your Java project and put the following code in it.

<?xml version="1.0" encoding="UTF-8"?>
<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>
      <id>jboss-public</id>
      <repositories>
        <repository>
          <id>jboss-public-repository</id>
          <name>JBoss Public Maven Repository Group</name>
          <url>http://repository.jboss.org/nexus/content/groups/public/</url>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>jboss-public</activeProfile>
  </activeProfiles>
</settings>

This tells Maven to search the repository hosted at https://repository.jboss.org when resolving dependencies for your application. The repository must be addressed with HTTP or HTTPS. If you require a file:// address, then see the Unmanaged Dependencies article.

We can test the settings locally by adding the -s option to any Maven task. But first, we’ll need to add a new dependency to the project. The jboss.web.servlet-api library is a good example because it’s only available on the JBoss repository. Add the follow element to your project’s pom.xml:

<dependency>
  <groupId>jboss.web</groupId>
  <artifactId>servlet-api</artifactId>
  <version>2.1.0.GA</version>
</dependency>

Now run the following command and Maven will download the artifact.

$ mvn -s settings.xml dependency:list
[INFO] Scanning for projects...
...
Downloading: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.pom
Downloaded: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.pom (195 B at 0.2 KB/sec)
Downloading: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.jar
Downloaded: http://repository.jboss.org/nexus/content/groups/public/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.jar (84 KB at 90.8 KB/sec)

If we had not used the custom settings file, the build would have failed with Maven producing an error like this:

Downloading: http://repo.maven.apache.org/maven2/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.pom
[WARNING] The POM for jboss.web:servlet-api:jar:2.1.0.GA is missing, no dependency information available
Downloading: http://repo.maven.apache.org/maven2/jboss/web/servlet-api/2.1.0.GA/servlet-api-2.1.0.GA.jar
...
[ERROR] Failed to execute goal on project helloworld: Could not resolve dependencies for project com.example:helloworld:jar:1.0-SNAPSHOT: Could not find artifact jboss.web:servlet-api:jar:2.1.0.GA in central (http://repo.maven.apache.org/maven2) -> [Help 1]

Now add the settings.xml and the pom.xml changes to your Git repository and deploy to Heroku like so:

$ git add pom.xml settings.xml
$ git commit -m "adding jboss servlet-api dependency"
$ git push heroku master

As Maven runs on the dyno, we see the same output we saw locally. This works because Heroku detects the settings.xml file in the root directory, and adds the -s option to the Maven command. Next, we’ll discuss how to customize this location.

Defining the MAVEN_SETTINGS_PATH config variable

If you do not want the settings.xml file in the root directory or if you intend to frequently change between different setting configurations, you may prefer to put a settings file in a custom location. Heroku provides this capability with the MAVEN_SETTINGS_PATH config variable.

We can demonstrate this feature by moving the existing settings.xml into a support/ directory and renaming it like so:

$ mkdir -p support
$ git mv settings.xml support/jboss-settings.xml

Now we tell Heroku where the settings file is located by defining MAVEN_SETTINGS_PATH relative to the root directory.

$ heroku config:set MAVEN_SETTINGS_PATH=support/jboss-settings.xml

Before testing the change, we increment the version of servlet-api – forcing Maven to download it again. Change the dependency in the pom.xml to version 2.1.1.GA. It should look like this:

<dependency>
  <groupId>jboss.web</groupId>
  <artifactId>servlet-api</artifactId>
  <version>2.1.1.GA</version>
</dependency>

Now commit the changes to Git, and redeploy to Heroku like so:

$ git commit -am "moved settings file and incremented servlet-api version"
$ git push heroku master

Once again, Maven will download the dependency from the JBoss repository. This provides a bit of flexibility, but sometimes a custom location in your project is not enough. You may want to keep the file out of your code base altogether.

Defining the MAVEN_SETTINGS_URL config variable

When the MAVEN_SETTINGS_URL config variable is defined, Heroku will download the file at the given location and use it to configure Maven. Before demonstrating this, we must unset the variable we defined in the previous example because it will take precedence if both variables are set:

$ heroku config:unset MAVEN_SETTINGS_PATH

Now we can use a settings.xml from a publicly available source such as the Torquebox Application Server code-base. Set the config variable like this:

$ heroku config:set MAVEN_SETTINGS_URL="https://raw.githubusercontent.com/torquebox/torquebox/master/support/settings.xml"

As before, increment the servlet-api version to 2.1.2.GA, add the pom.xml to the Git repo, commit the changes and redeploy to Heroku. Maven will download the new artifact from the JBoss repository as it did earlier.

The JBoss repository is convenient because it is public – it does not require a password to access. But not all repositories are quite so open.

Using password protected repositories

Some artifact repositories require a username and password to access. Many times, the repository is a private server hosting internal artifacts. When this is the case, credentials for accessing the repository must be provided in the settings.xml, which can be a problem if the file is checked into a Git repository.

Fortunately, Maven settings files can detect environment variables. Any token in the form ${env.ENV_VAR} (where ENV_VAR is the name of a variable) will resolve to the value of the associated environment variable. Thus we can define the password for a private Maven repo as a Heroku config variable like this:

$ heroku config:set MAVEN_REPO_PASSWORD="deployment123"

Then we can use the variable in our settings.xml file by creating a <server> element that matches the <id> of the <repository> element in the <activeProfile>.

<servers>
  <server>
    <id>my-private-repo</id>
    <username>deployment</username>
    <password>${env.MAVEN_REPO_PASSWORD}</password>
  </server>
</servers>

In order to demonstrate this, you will need a private Maven repository. You can create a repository by downloading Sonatype Nexus and following the instructions for securing a repository. Or you may use a hosted version of JFrog Artifactory.

In either case a private repository can be used to publish internal artifacts and include them in your Heroku applications.

For more information on customizing Maven with a settings file, please see the Maven Settings Reference from Apache.org.

Keep reading

  • Working with Maven

Feedback

Log in to submit feedback.

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices