EAP 7/8 Galleon settings xml in the building process

Environment

• Red Hat Enterprise Application Platform
  • 8.x
  • 7.x
    • building
• Red hat OpenShift Container Platform (OCP)
  • 4.x

Issue

• Where to find /home/jboss/.m2/settings.xml in EAP 7/8
• What does settings.xml have?
• We are building EAP8 image with a Dockerfile, the mvn command is called by the assemble script (RUN /usr/local/s2i/assemble) inside the dockerfile when provisioning the server.

Resolution

There is a /tmp/galleon-settings.xml in the build, which is a copy of the /home/jboss/.m2/settings.xml.
This file will contain the mirror, repositories, that you configure for customizations.

In the matter of customizations, the user can provide a settings.xml file in the directory /tmp/src/galleon, evidently the advice is to copy the one in /home/jboss/.m2 and evolve it to the desired settings. The Source-to-Image logic expects the /tmp/src dir to contain application sources, in which the galleon directory containing the settings would be located, the so-called user-specific settings.xml.

If both files exist: the user one and the default one, their contents will get merged, with the user-specific settings.xml being dominant.

The environment variable GALLEON_MAVEN_ARGS should be enough to use a custom settings.xml:

GALLEON_MAVEN_ARGS= -gs ../global-setting.xml  <--- example

Explanation:

Important notes:

• If both files exist, their contents get merged, with the user-specific settings.xml being dominant.
• The GALLEON_MAVEN_ARGS are only useful if GALLEON_PROVISION_LAYERS is set - see reasons on EAP 8 Galleon legacy vs non-legacy build
• For disconnected environments see EAP 8 build on disconnected environment.
• The MAVEN_MIRROR_URL is not to be set when you control completely the settings.xml, otherwise an extra mirror is added.
• GALLEON_PROVISION_CHANNELS selects the provisioning channels that fetch the Building jars.

Root Cause

The S2I logic expects the /tmp/src directory to contain application sources, in which the galleon directory containing the settings would be located.
During the package process 'eap-maven-plugin' is invoked with package goal which should download the eap8.0 channel's meta-data and download artifacts from this channel & feature packs & provision the server.

Example settings.xml:

<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">
<!-- 
<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">
 -->
<!-- <localRepository>C:\path\m3-repository</localRepository> -->
<servers>
<server>
<id>maven-central</id>
<username>${env.MAVEN_MIRROR_USER}</username>
<password>${env.MAVEN_MIRROR_PASSWORD}</password>
</server>
</servers>
<!--     <pluginGroups> -->
<!--         <pluginGroup>com.aexample.plugins</pluginGroup> -->
<!--     </pluginGroups> -->
<mirrors>
<mirror>
<id>maven-central</id>
<mirrorOf>central</mirrorOf>
<name>Mirror of the Maven central repository provided by OpenPaaS</name>
<url>${env.MAVEN_MIRROR_URL}</url>
</mirror>
</mirrors>
</settings>

Example above uses MAVEN_MIRROR_URL to set the mirror URL. Otherwise use a custom settings.xmls, example custom settings.xml user can have:

<server>
<id>Example-Artifactory</id>
<username>${env.MY_USER}</username>
<password>${env.MY_PASSWORD}</password>
</server>
</servers>

Attention that MAVEN_MIRROR_USER and MAVEN_MIRROR_PASSWORD do not exist in the S2I build process, it is part of the Maven and passed on the settings.xml as above. Also the environment might collide (without unique names), see details Content from github.com is not included.maven - build module.

For OpenJDK details, see Custom setting.xml in OpenJDK container build.

Diagnostic Steps

Custom settings.xml injection troubleshooting:

In case the file is not found, the following custom file is reported:

[ERROR] Error executing Maven.
java.io.FileNotFoundException: The specified global settings file does not exist: /opt/jboss/container/wildfly/s2i/galleon/provisioning/apple-setting.xml
    at org.apache.maven.cli.configuration.SettingsXmlConfigurationProcessor.process (SettingsXmlConfigurationProcessor.java:117)
    at org.apache.maven.cli.MavenCli.configure (MavenCli.java:1169)

In case the file is found but not readable, the following custom file is reported:

[FATAL] Non-readable settings /opt/jboss/container/wildfly/s2i/galleon/provisioning/apple-setting.xml: input contained no data @ /opt/jboss/container/wildfly/s2i/galleon/provisioning/apple-setting.xml
    at org.apache.maven.settings.building.DefaultSettingsBuilder.build (DefaultSettingsBuilder.java:129)

For a full diagnostic investigation:

For OCP build:

• Get the inspect bundle
• Verify the Buildconfig and build logs.

For local build:

• Get the Dockerfile and build logs
• Verify any problem related to Galleon or Docker.

Options for troubleshooting:

ENV GALLEON_MAVEN_ARGS="-Dverbose" 
ENV SCRIPT_DEBUG true

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.