14.5. Configuring Maven Proxies and HTTP Proxies through settings.xml

Overview

You can optionally configure the Maven proxy using a standard Maven settings.xml file. For example, this approach is particularly convenient in a development environment, because it makes it possible to store your build time settings and your run time settings in one place.

Enabling the settings.xml configuration approach

To configure Fabric to read its Maven configuration from a Maven settings.xml file, perform the following steps:
  1. Delete the org.ops4j.pax.url.mvn.repositories property setting from the io.fabric8.agent PID in the default profile, using the following console command: 
    profile-edit --delete --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories default
    When the repositories setting is absent, Fabric implicitly switches to the settings.xml configuration approach.
    Note
    This step simultaneously clears both the repositories list used by the Fabric8 agent and the repositories list used by the Maven proxy server (because the Maven proxy's repository list is normally copied straight from the Fabric8 agent's repository list).
  2. Set the io.fabric8.maven.settings property from the io.fabric8.maven PID in the default profile to the location of the Maven settings.xml file. For example, if your settings.xml file is stored in the location, /home/fuse/settings.xml, you would set the io.fabric8.maven.settings property as follows: 
    profile-edit --pid io.fabric8.maven/io.fabric8.maven.settings='/home/fuse/settings.xml' default
    Note
    The effect of this setting is to configure the Maven proxy server to takes its Maven configuration from the specified settings.xml file. The Fabric8 agent is not affected by this setting.
  3. In order to configure the Fabric8 agent with the Maven settings.xml, set the org.ops4j.pax.url.mvn.settings property from the io.fabric8.agent PID in the default profile to the location of the Maven settings.xml file. For example, if your settings.xml file is stored in the location, /home/fuse/settings.xml, you would set the org.ops4j.pax.url.mvn.settings property as follows: 
    profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.settings='/home/fuse/settings.xml' default
    Important
    If you configure a HTTP proxy in your settings.xml file, it is essential to configure the ensemble hosts (where the Maven proxies are running) as HTTP non-proxy hosts. Otherwise, the Fabric8 agent tries to connect to the local Maven proxy through the HTTP proxy (which is an error).

Adding a remote Maven repository

To add a new remote Maven repository to your settings.xml file, open the settings.xml file in a text editor and add a new repository XML element. For example, to create an entry for the JBoss A-MQ public Maven repository, add a repository element as shown: 
<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>my-fuse-profile</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <!--
         | Add new remote Maven repositories here
          -->
        <repository>
          <id>jboss-fuse-public-repository</id>
          <url>https://repo.fusesource.com/nexus/content/groups/public/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
        ...
      </repositories>
  </profiles>
  ...
</settings>
The preceding example additionally specifies that release artifacts can be downloaded, but snapshot artifacts cannot be downloaded from the repository.

Configuring a HTTP proxy

To configure a HTTP proxy (which will be used when connecting to remote Maven repositories), open the settings.xml file in a text editor and add a new proxy XML element as a child of the proxies XML element. The definition of the proxy follows the standard Maven syntax. For example, to create a proxy for the HTTP (insecure) protocol with host, 192.0.2.0, and port, 8080, add a proxy element as follows: 
<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">
  ...
  <proxies>
    <proxy>
      <id>fuse-proxy-1</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>192.0.2.0</host>
      <port>8080</port>
      <nonProxyHosts>ensemble1|ensemble2|ensemble3</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>
You must remember to add the ensemble hosts (where the Maven proxy servers are running) to the list of HTTP non-proxy hosts in the nonProxyHosts element. This ensures that the Fabric8 agents do not attempt to connect to the Maven proxies through the HTTP proxy, but make a direct connection instead. In the preceding example, the ensemble host names are ensemble1, ensemble2, and ensemble3.
You can also add a proxy for secure HTTPS connections by adding a proxy element configured with the https protocol.

Alternative approaches to configuring a HTTP proxy

There are some alternative approaches you can use to configure a HTTP proxy, but generally these other approaches are not as convenient as editing the settings.xml file. For example, you could take the approach of setting the http.proxyHost and http.proxyPort system properties in the InstallDir/etc/system.properties file (just like the approach for a standalone, non-Fabric container): 
http.proxyHost=192.0.2.0
http.proxyPort=8080
This configuration suffers from the disadvantage that it also affects the Fabric8 agents, preventing them from accessing the Maven proxy server directly (on the internal network). In order to compensate for this, you would need to configure the list of non-proxy hosts to include the hosts where the Fabric servers (ensemble servers) are running, for example: 
http.nonProxyHosts=ensemblehost1|ensemblehost2|ensemblehost3

Reference

For a detailed description of the syntax of the Maven settings.xml file, see the Maven Settings Reference. But please note that not all of the features documented there are necessarily supported by Fabric.