Installing on Apache Karaf

Red Hat Fuse 7.8

Installing Red Hat Fuse on the Apache Karaf container

Red Hat Fuse Documentation Team

Abstract

It is easy to install Red Hat Fuse and tailor the installation to a particular environment.

Preface

Red Hat Fuse is a lightweight, flexible integration platform that enables rapid integration across the extended enterprise—on-premise or in the cloud.

Based on Apache Camel, Fuse leverages pattern-based integration, a rich connector catalog, and extensive data transformation capabilities to enables users to integrate anything.

Chapter 1. Install Fuse for Development on Apache Karaf

To develop Fuse applications that run on Karaf, install Fuse locally as described in the following topics:

1.1. Prepare to install Fuse on Apache Karaf

To prepare to install Fuse on Apache Karaf, check your system to ensure that it meets hardware requirements, is a supported platform, and has a supported Java runtime. Also, confirm that you plan to use supported standard software for web services, APIs, and transport protocols.

Procedure

  1. On the system on which you plan to install Fuse, confirm that it has:

    • 250 MB of free disk space
    • 2 GB of RAM

    This hardware requirement is for a full installation of Fuse on Apache Karaf. In addition, a system that is running Fuse requires space for caching, persistent message stores, and other functions. The actual requirement is dependent on what your Fuse applications do.

  2. Confirm that the system on which you plan to install Fuse is running a supported platform. Red Hat tests and supports Fuse products on the platforms that are listed in Red Hat Fuse Supported Configurations.
  3. Confirm that your system is running a Java runtime that is supported by Fuse on Apache Karaf. See Supported Java Versions in Red Hat Fuse Supported Configurations.
  4. Ensure that your Java runtime is not installed under a directory path that includes whitespace. For example, C:\Program Files\Java\jdk8 is not an acceptable path. Whitespace in paths causes unpredictable errors in Fuse on Apache Karaf at run time.
  5. Check the list of Red Hat Fuse Supported Standards to confirm that you are using supported standard software.

1.2. Install Fuse on Apache Karaf

The standard installation package for Fuse 7.8 on Karaf is available for download from the Red Hat Customer Portal. It installs the standard assembly of the Apache Karaf container, and provides the full Fuse technology stack.

It is possible to create your own custom assembly of Fuse 7.8, which contains a customized subset of the Fuse features and bundles. The custom quickstart demonstrates how to use Maven to create a custom assembly of Red Hat Fuse. You can install all of the quickstarts from a downloadable file available on the Fuse Software Downloads page.

Prerequisite

The system on which you plan to install Fuse meets the hardware and software requirements described in Section 1.1, “Prepare to install Fuse on Apache Karaf”.

Procedure

  1. In a browser, go to the Fuse Software Downloads page.

    If you are not already logged in to the Red Hat customer portal, there is a prompt to log in and then the download page appears (your account must be associated with a Red Hat Fuse subscription).

  2. In the Fuse Software Downloads page, to the right of Red Hat Fuse 7.8 on Karaf Installer, click Download to obtain a local zip file.

  3. Extract the contents of the zip file into a directory for which you have all permissions.

    Do not unpack the zip file into a directory that has spaces or any of the following special characters in its path name: #, %, ^, ". For example, do not unpack into C:\Documents and Settings\Greco#Roman\Desktop\fuse.

  4. If you are using the IBM JDK, perform the following additional steps:

    1. In your Fuse installation directory, in the /lib/endorsed directory, remove the saaj-api .jar file, for example: 

      rm lib/endorsed/org.apache.servicemix.specs.saaj-api-1.3-2.9.0.jar

    2. Set the JAVA_OPTS environment variable as follows: 

      JAVA_OPTS=-Xshareclasses:none

      You must set the JAVA_OPTS environment variable before you start the Karaf container.

  5. Add an administrator user to enable remote access to the Fuse on Karaf container and to access the Fuse Console.

    By default, no users are defined for the container. You can run the container in the foreground in this case, but you cannot access the container remotely and you cannot run it in the background. It is recommended that you create at least one user with the admin role by following these steps:

    1. In a text editor, open the etc/users.properties file, which is in your Fuse installation directory.

    2. Locate the following lines: 

      #admin = admin,_g_:admingroup
#_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
    3. For each line, remove the leading # character to uncomment the line.
    4. In the first line, change the first instance of admin to a username that you choose, for example user1.

    5. In the same line, change the second instance of admin to a password for that user, for example passw0rd.

      For example: 

      user1 = passw0rd,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
    6. Save and close the file.
  6. To start Fuse, run bin/fuse on Linux/Unix or bin\fuse.bat on Windows.
  7. Optionally, to access the Fuse Console, open the provided URL in a web browser and login with the username and password that you set in the etc/users.properties file. For more information about using the Fuse Console see Managing Fuse.

1.3. About running Fuse on Karaf offline

You can run the Apache Karaf container in offline mode, that is, without an Internet connection. However, if you are planning to deploy custom applications to the container, it might be necessary to download additional dependencies to a local Maven repository before you can run the container in offline mode with these applications.

To run the Apache Karaf container in offline mode, it is necessary to distinguish between the following kinds of dependencies:

  • Runtime dependencies are dependencies that are required to run the Apache Karaf container in its default configuration.
  • Build-time dependencies are dependencies that are required to build a custom application, which might include third-party libraries.

Here is a summary of what can be done in offline mode and what needs to be done in online mode (with an Internet connection):

  • Running the Apache Karaf container in its default configuration is supported in offline mode. The default configuration of the Apache Karaf container is specified by the featuresBoot property in the etc/org.apache.karaf.features.cfg file. The required dependencies are provided in the system/ sub-directory of the installation.
  • Installing additional features is, in general, not supported in offline mode. In principle, you can use the features:install command to install any of the features from the standard feature repositories (as specified by the featuresRepositories property in the etc/org.apache.karaf.features.cfg file), but the majority of these features must be downloaded from the Internet and are thus not supported in offline mode.
  • Deploying custom applications is, in general, not supported in offline mode. There may be some cases where an application with a minimal set of build-time dependencies is deployable offline. However, custom applications typically have third-party dependencies that require an Internet connection so that JAR files can be downloaded by Apache Maven.

Additional resource

Section 3.3, “Using local Maven repositories”

1.4. Optionally use standalone Apache distributions

Red Hat Fuse provides an additional package to download, which contains the standard distributions of Apache Camel and Apache CXF. If you want to use a standard, upstream distribution of Apache Camel or Apache CXF (without the OSGi container) use the archived versions in the downloaded extras package.

Procedure

  1. Log in to the Red Hat customer portal.
  2. Go to the Red Hat Customer Portal→Downloads→Red Hat Fuse→Downloads page.
  3. Select 7.8.0 from the Version drop-down list on the Software Downloads page.

  4. Download the Red Hat Fuse 7.8.0 Extras archive.

    The extras archive file contains the following archive files nested inside it:

    • apache-camel-2.23.2.fuse-780036-redhat-00001.zip
    • apache-cxf-3.3.6.fuse-780029-redhat-00001.zip
  5. Copy these files to the desired location and decompress them using the appropriate utility for your platform.
Warning

Do not unpack an archive file into a folder that has spaces in its path name. For example, do not unpack into C:\Documents and Settings\Greco Roman\Desktop\fuse.

Chapter 2. Applying Hotfix Patch to Fuse on Apache Karaf

2.1. Patching Features and Bundles

Patches are ZIP archives that contain the updated versions of files present in Fuse on Apache Karaf installation. These include:

  • Bundles: These are the most common and in the simplest case, hotfix patch may include single bundle.
  • Configuration files and scripts that are present respectively in $FUSE_HOME/etc and $FUSE_HOME/bin directories.
  • Libraries that are not ordinary bundles and reside in $FUSE_HOME/lib directory.
  • Feature definition changes: Normally Karaf features are included in descriptors available in the $FUSE_HOME/system directory, but hotfix patches do not change these files. Instead, hot fix patch may alter feature override file which is $FUSE_HOME/etc/org.apache.karaf.features.xml. This allows you to alter feature definitions in hotfix manner by upgrading given feature’s bundles or even make given feature use additional bundle.

Difference between Upgrading and Hotfix Patches

  • Hotfix Patch: A hotfix patch contains fixes for only one or more critical bugs. These are intended to be applied on top of your current Red Hat Fuse distribution. Its main purpose is to update some of the bundles and libraries in an existing distribution.
  • Upgrading: The Fuse on Apache Karaf upgrade mechanism enables you apply fixes to an Apache Karaf container without needing to reinstall an updated version of Fuse on Karaf. It also allows you to roll back the upgrade, if the upgrade causes problems with your deployed applications. The Fuse on Apache Karaf upgrade process updates any files, including bundle JARs, configuration files, and any static files.

For Fuse on Apache Karaf Standalone you can apply the patch using commands from the Karaf console’s patch shell. This approach is non-destructive and reversible. Following procedure can also be used for upgrading Red Hat Fuse on Apache Karaf. For more information of upgrading see Upgrading Fuse on Apache Karaf.

2.2. Applying a Hotfix Patch to Red Hat Fuse on Apache Karaf

You can use the hotfix mechanism to update the available feature definitions and bundles at the same time. The procedure to apply a hotfix patch to the Fuse on Apache Karaf installation is as follows.

Procedure

  1. Make a full backup of your Fuse on Apache Karaf installation before upgrading.

  2. Open the terminal and start Fuse on Apache karaf server. 

    [user@FUSE_HOME/bin ~] $ ./fuse
  3. Optional: Download the required patch from the Customer Portal and skip to Step 5.

  4. Enter the patch:find command to find available patches in the Maven repositories. For example: 

    karaf@root()> patch:find
Found new remote patch at mvn:org.jboss.redhat-fuse/fuse-karaf-patch-repository/7.8.0.fuse-sb2-780040/zip
You can add the patch using "patch:add mvn:org.jboss.redhat-fuse/fuse-karaf-patch-repository/7.8.0.fuse-sb2-780040/zip" command, or simply use "patch:find --add" option.
    Note

    You may use the patch:find command with the --add option to find the latest patch and add it to the container’s environment.

  5. Add the patch to the container’s environment by entering the patch:add command. For example: 

    karaf@root()> patch:add mvn:org.jboss.redhat-fuse/fuse-karaf-patch-repository/7.8.0.fuse-sb2-780040/zip
[name]                                             [installed] [rollup] [description]                                      [CVEs]
fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040 false       false    fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040 CVE-2020-28052

Current patch mechanism version: 7.8.0.fuse-780038
New patch mechanism version detected: 7.8.0.fuse-780040
Please run "patch:update" command to upgrade patching mechanism to version 7.8.0.fuse780040
    Note

    Instead of using the patch:add command, you can also add a patch file automatically by copying the .zip patch file into the FUSE_HOME/patches directory.

  6. Optional: Enter the patch:update command to update the patch mechanism itself: 

    karaf@root()> patch:update
Current patch mechanism version: 7.8.0.fuse-780038
New patch mechanism version detected: 7.8.0.fuse-780040
Uninstalling patch features in version 7.8.0.fuse-780038
Installing patch features in version 7.8.0.fuse-780040
    Important

    If the patch mechanism is updated after running the patch:update command, you must re-run the patch:add command to add a patch to the container’s environment.

  7. Simulate installing the patch by entering the patch:simulate command.

    This generates a log of the changes that will be made to the container when the patch is installed, but will not make any actual changes to the container. Review the simulation log to understand these changes.

  8. Enter the patch:list command to view a list of added patches. In this list, the entries under the [name] heading are patch IDs. 

    karaf@root()> patch:list
[name]                                             [installed] [rollup] [description]                                      [CVEs]
fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040 false       false    fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040 CVE-2020-28052

  9. If the patch contains explicit CVE metadata, you can enter the patch:show command to view more details: 

    karaf@root()> patch:show fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040
Patch ID: fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040
Patch Commit ID: a2d7cf58e21116cde66c97232aea4be1ec304400
#### 1 CVE fix:
 - CVE-2020-28052: bouncycastle: password bypass in OpenBSDBCrypt.checkPassword utility possible
   Bugzilla link: https://bugzilla.redhat.com/show_bug.cgi?id=1912881
   CVE link: https://cve.mitre.org/cgi-bin/cvename.cgi?name=2020-28052

  10. Apply a patch to the container by entering the patch:install command and specifying the patch ID for the patch that you want to apply. For example: 

    patch:install fuse-karaf-maintenance-patch-7.8.0.fuse-sb2-780040

2.3. Rolling back a Patch

You can rollback the installed hotfix patch and restore it to pre-patch behavior using the patch:rollback command, as follows:

Procedure

  1. Enter the patch:list command to obtain the patch ID of the most recently installed patch.

  2. To rollback the updated bundle enter the following command: 

    karaf@root()> patch:rollback my-patch-x
INFO : org.jboss.fuse.modules.patch.patch-management (2): Rolling back non-rollup patch "my-patch-x"
removing overriden feature: hawtio-rbac/2.0.0.fuse-000117
refreshing features
Enter feature:info command to view the information about the feature.
    karaf@root()> feature:info hawtio-rbac
Feature hawtio-rbac 2.0.0.fuse-000117
Details:
      Installs the hawtio RBAC enabler bundle(s)
Feature has no configuration
Feature has no configuration files
Feature has no dependencies.
Feature contains followed bundles:
      mvn:io.hawt/hawtio-osgi-jmx/2.0.0.fuse-000117
Feature has no conditionals.

2.4. Patching Red Hat Fuse application

Using the new patch-maven-plugin mechanism you can apply a patch to your Red Hat Fuse application. This mechanism allows you to change the individual versions provided by different Red Hat Fuse BOMS, for example, fuse-springboot-bom and fuse-karaf-bom.

2.4.1. About patch-maven-plugin

The patch-maven-plugin performs following operations:

  • Retrieve the patch metadata related to current Red Hat Fuse BOMs.
  • Apply the version changes to <dependencyManagement> imported from the BOMs.

After the patch-maven-plugin fetches the metadata, it iterates through all managed and direct dependencies of the project where the plugin was declared and replaces the dependency versions (if they match) using CVE/patch metadata. After versions are replaced, Maven build continues and progresses through standard Maven project stages.

2.4.2. Applying patch to Red Hat Fuse applications

The purpose of patch-maven-plugin is to update the versions of the dependencies listed in the Red Hat Fuse BOM to the versions specified in the patch metadata of the patch that you wish to apply to your applications.

Procedure

Following procedure explains how to apply the patch to your application.

  1. Add patch-maven-plugin to your project’s pom.xml file. The version of the patch-maven-plugin must be the same as the version of the Fuse BOM. 

    <build>
    <plugins>
        <plugin>
            <groupId>org.jboss.redhat-fuse</groupId>
            <artifactId>patch-maven-plugin</artifactId>
            <version>${version.org.jboss-redhat-fuse}</version>
            <extensions>true</extensions>
        </plugin>
    </plugins>
</build>

  2. When you run any one of the mvn clean deploy or mvn validate or mvn dependency:tree commands, the plugin searches through the project modules to check whether one of Red Hat Fuse BOMs is used. Only two are considered as the supported BOMs:

    • org.jboss.redhat-fuse:fuse-karaf-bom: for Fuse Karaf BOM
    • org.jboss.redhat-fuse:fuse-springboot-bom: for Fuse Spring Boot BOM

  3. If none of the above BOMs are found, the plugin will display following messages: 

    $ mvn clean install
[INFO] Scanning for projects...
[INFO]

========== Red Hat Fuse Maven patching ==========

[INFO] [PATCH] No project in the reactor uses Fuse Karaf or Fuse Spring Boot BOM. Skipping patch processing.
[INFO] [PATCH] Done in 3ms

  4. If both Fuse BOMs are found, the patch-maven-plugin stops with the following warning: 

    $ mvn clean install
[INFO] Scanning for projects...
[INFO]

========== Red Hat Fuse Maven patching ==========

[WARNING] [PATCH] Reactor uses both Fuse Karaf and Fuse Spring Boot BOMs. Please use only one. Skipping patch processing.
[INFO] [PATCH] Done in 3ms

  5. The patch-maven-plugin attempts to fetch one of the following Maven metadata values.

    • For the projects with Fuse Karaf BOM, the org.jboss.redhat-fuse/fuse-karaf-patch-metadata/maven-metadata.xml is resolved. This is the metadata for the artifact with the org.jboss.redhat-fuse:fuse-karaf-patch-metadata:RELEASE coordinates.

    • For the projects with Fuse Spring Boot BOM project, the org.jboss.redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml is resolved. This is the metadata for the artifact with the org.jboss.redhat-fuse:fuse-springboot-patch-metadata:RELEASE coordinates.

      Example metadata generated by Maven

      <?xml version="1.0" encoding="UTF-8"?>
<metadata>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>fuse-springboot-patch-metadata</artifactId>
  <versioning>
    <release>7.8.1.fuse-sb2-781025</release>
    <versions>
      <version>7.8.0.fuse-sb2-780025</version>
      <version>7.7.0.fuse-sb2-770010</version>
      <version>7.7.0.fuse-770010</version>
      <version>7.8.1.fuse-sb2-781025</version>
    </versions>
    <lastUpdated>20201023131724</lastUpdated>
  </versioning>
</metadata>

  6. The patch-maven-plugin parses the metadata to select the version which is applicable to the current project. This is possible only for the Maven projects using Fuse BOM with version 7.8.xxx. Only the metadata that matches the version range 7.8, 7.9 or later is applicable and only the latest version of the metadata is fetched.

  7. The patch-maven-plugin collects a list of remote Maven repositories to be used when downloading the patch metadata identified by groupId, artifactId and version found in previous steps. These Maven repositories are the ones that are listed in the project’s <repositories> elements in the active profiles and also the repositories from settings.xml file. 

    $ mvn clean install
[INFO] Scanning for projects...
[INFO]

========== Red Hat Fuse Maven patching ==========

[INFO] [PATCH] Reading patch metadata and artifacts from 2 project repositories
[INFO] [PATCH]  - local-nexus: http://everfree.forest:8081/repository/maven-releases/
[INFO] [PATCH]  - central: https://repo.maven.apache.org/maven2
Downloading from local-nexus: http://everfree.forest:8081/repository/maven-releases/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml
...

  8. Optionally, if you wish to use a offline repository, you can use -Dpatch option to specify a ZIP file which is produced by fuse-karaf/fuse-karaf-patch-repository or fuse-springboot/fuse-springboot-patch-repository modules of jboss-fuse/redhat-fuse project. These ZIP files have the same internal structure as the Maven repository structure. For example, 

    $ mvn clean install -Dpatch=../../../test/resources/patch-3.zip
[INFO] Scanning for projects...
[INFO]

========== Red Hat Fuse Maven patching ==========

[INFO] [PATCH] Reading metadata and artifacts from /data/sources/github.com/jboss-fuse/redhat-fuse/fuse-tools/patch-maven-plugin/src/test/resources/patch-3.zip
Downloading from fuse-patch: zip:file:/tmp/patch-3.zip-1742974214598205745/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml
Downloaded from fuse-patch: zip:file:/tmp/patch-3.zip-1742974214598205745/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml (406 B at 16 kB/s)
Downloading from fuse-patch: zip:file:/tmp/patch-3.zip-1742974214598205745/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/7.8.0.fuse-sb2-781023/fuse-springboot-patch-metadata-7.8.0.fuse-sb2-781023.xml
Downloaded from fuse-patch: zip:file:/tmp/patch-3.zip-1742974214598205745/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/7.8.0.fuse-sb2-781023/fuse-springboot-patch-metadata-7.8.0.fuse-sb2-781023.xml (926 B at 309 kB/s)
[INFO] [PATCH] Resolved patch descriptor: /home/user/.m2/repository/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/7.8.0.fuse-sb2-781023/fuse-springboot-patch-metadata-7.8.0.fuse-sb2-781023.xml
...

  9. Whether the metadata comes from remote repository, local repository or ZIP file, it is analyzed by the patch-maven-plugin. The fetched metadata contains list of CVEs and for each CVE we have a list of affected Maven artifacts (specified by glob patterns and version ranges) together with a version that contains a fix for a given CVE. For example, 

    <?xml version="1.0" encoding="UTF-8" ?>

<metadata xmlns="urn:redhat:fuse:patch-metadata:1">
    <product-bom groupId="org.jboss.redhat-fuse" artifactId="fuse-springboot-bom" versions="[7.8,7.9)" />
    <cves>
        <cve id="CVE-2020-xyz" description="Jetty can be configured to listen on port 8080"
                cve-link="https://nvd.nist.gov/vuln/detail/CVE-2020-xyz"
                bz-link="https://bugzilla.redhat.com/show_bug.cgi?id=42">
            <affects groupId="org.eclipse.jetty" artifactId="jetty-*" versions="[9.4,9.4.32)" fix="9.4.32.v20200930" />
            <affects groupId="org.eclipse.jetty.http2" artifactId="http2-*" versions="[9.4,9.4.32)" fix="9.4.32.v20200930" />
        </cve>
    </cves>
    <fixes />
</metadata>

  10. Finally a list of fixes specified in patch metadata is consulted when iterating over all managed dependencies in current project. These dependencies (and managed dependencies) that match are changed to fixed versions. For example: 

    $ mvn clean install -U
[INFO] Scanning for projects...
[INFO

========== Red Hat Fuse Maven patching ==========

[INFO] [PATCH] Reading patch metadata and artifacts from 2 project repositories
[INFO] [PATCH]  - local-nexus: http://everfree.forest:8081/repository/maven-releases/
[INFO] [PATCH]  - central: https://repo.maven.apache.org/maven2
Downloading from local-nexus: http://everfree.forest:8081/repository/maven-releases/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml
Downloading from central: https://repo.maven.apache.org/maven2/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml
Downloaded from local-nexus: http://everfree.forest:8081/repository/maven-releases/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/maven-metadata.xml (363 B at 4.3 kB/s)
[INFO] [PATCH] Resolved patch descriptor: /home/user/.m2/repository/org/jboss/redhat-fuse/fuse-springboot-patch-metadata/7.8.0.fuse-sb2-780032/fuse-springboot-patch-metadata-7.8.0.fuse-sb2-780032.xml
[INFO] [PATCH] Patch metadata found for org.jboss.redhat-fuse/fuse-springboot-bom/[7.8,7.9)
[INFO] [PATCH]  - patch contains 1 CVE fix
[INFO] [PATCH] Processing managed dependencies to apply CVE fixes... (https://nvd.nist.gov/vuln/detail/CVE-2020-xyz, https://bugzilla.redhat.com/show_bug.cgi?id=42_
[INFO] [PATCH] - CVE-2020-xyz: Jetty can be configured to expose itself on port 8080
[INFO] [PATCH]   Applying change org.eclipse.jetty/jetty-*/[9.4,9.4.32) -> 9.4.32.v20200930
[INFO] [PATCH]    - managed dependency: org.eclipse.jetty/jetty-alpn-client/9.4.30.v20200611 -> 9.4.32.v20200930
...
[INFO] [PATCH]    - managed dependency: org.eclipse.jetty/jetty-openid/9.4.30.v20200611 -> 9.4.32.v20200930
[INFO] [PATCH]   Applying change org.eclipse.jetty.http2/http2-*/[9.4,9.4.32) -> 9.4.32.v20200930
[INFO] [PATCH]    - managed dependency: org.eclipse.jetty.http2/http2-client/9.4.30.v20200611 -> 9.4.32.v20200930
...
[INFO] [PATCH] Done in 635ms

=================================================

Skipping the patch

In case when you do not wish to apply a specific patch to your project, the patch-maven-plugin provides a skip option. Assuming that you have already added patch-maven-plugin to project’s pom.xml file, and you don’t wish for the versions to be altered, you can use one of the following method to skip the patch.

  • Add the skip option to your project’s pom.xml file as follows. 
<build>
    <plugins>
        <plugin>
            <groupId>org.jboss.redhat-fuse</groupId>
            <artifactId>patch-maven-plugin</artifactId>
            <version>${version.org.jboss-redhat-fuse}</version>
            <extensions>true</extensions>
            <configuration>
                <skip>true</skip>
            </configuration>
        </plugin>
    </plugins>
</build>
  • Or use -DskipPatch option when running the mvn command as follows. 
$ mvn dependency:tree -DskipPatch
[INFO] Scanning for projects...
[INFO]
[INFO] ------< org.jboss.redhat-fuse:cve-dependency-management-module1 >-------
[INFO] Building cve-dependency-management-module1 7.8.0.fuse-sb2-780033
[INFO] --------------------------------[ jar ]---------------------------------
...

As shown in the above output, the patch-maven-plugin was not invoked, which results in the patch not being applied to the application.

Chapter 3. Setting up Maven locally

Typical Fuse application development uses Maven to build and manage projects.

The following topics describe how to set up Maven locally:

3.1. Preparing to set up Maven

Maven is a free, open source, build tool from Apache. Typically, you use Maven to build Fuse applications.

Procedure

  1. Download the latest version of Maven from the Maven download page.

  2. Ensure that your system is connected to the Internet.

    While building a project, the default behavior is that Maven searches external repositories and downloads the required artifacts. Maven looks for repositories that are accessible over the Internet.

    You can change this behavior so that Maven searches only repositories that are on a local network. That is, Maven can run in an offline mode. In offline mode, Maven looks for artifacts in its local repository. See Section 3.3, “Using local Maven repositories”.

3.2. Adding Red Hat repositories to Maven

To access artifacts that are in Red Hat Maven repositories, you need to add those repositories to Maven’s settings.xml file. Maven looks for the settings.xml file in the .m2 directory of the user’s home directory. If there is not a user specified settings.xml file, Maven uses the system-level settings.xml file at M2_HOME/conf/settings.xml.

Prerequisite

You know the location of the settings.xml file in which you want to add the Red Hat repositories.

Procedure

In the settings.xml file, add repository elements for the Red Hat repositories as shown in this example: 

<?xml version="1.0"?>
<settings>

  <profiles>
    <profile>
      <id>extra-repos</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
       <repository>
            <id>redhat-ga-repository</id>
            <url>https://maven.repository.redhat.com/ga</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>redhat-ea-repository</id>
            <url>https://maven.repository.redhat.com/earlyaccess/all</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
          <id>jboss-public</id>
          <name>JBoss Public Repository Group</name>
          <url>https://repository.jboss.org/nexus/content/groups/public/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
            <id>redhat-ga-repository</id>
            <url>https://maven.repository.redhat.com/ga</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
        <pluginRepository>
            <id>redhat-ea-repository</id>
            <url>https://maven.repository.redhat.com/earlyaccess/all</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
        <pluginRepository>
          <id>jboss-public</id>
          <name>JBoss Public Repository Group</name>
          <url>https://repository.jboss.org/nexus/content/groups/public</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>extra-repos</activeProfile>
  </activeProfiles>

</settings>

3.3. Using local Maven repositories

If you are running the Apache Karaf container without an Internet connection, and you need to deploy an application that has dependencies that are not available offline, you can use the Maven dependency plug-in to download the application’s dependencies into a Maven offline repository. You can then distribute this customized Maven offline repository to machines that do not have an Internet connection.

Procedure

  1. In the project directory that contains the pom.xml file, download a repository for a Maven project by running a command such as the following: 

    mvn org.apache.maven.plugins:maven-dependency-plugin:3.1.0:go-offline -Dmaven.repo.local=/tmp/my-project

    In this example, Maven dependencies and plug-ins that are required to build the project are downloaded to the /tmp/my-project directory.

  2. Distribute this customized Maven offline repository internally to any machines that do not have an Internet connection.

3.4. Setting Maven mirror using environmental variables or system properties

When running the applications you need access to the artifacts that are in the Red Hat Maven repositories. These repositories are added to Maven’s settings.xml file. Maven checks the following locations for settings.xml file:

  • looks for the specified url
  • if not found looks for ${user.home}/.m2/settings.xml
  • if not found looks for ${maven.home}/conf/settings.xml
  • if not found looks for ${M2_HOME}/conf/settings.xml
  • if no location is found, empty org.apache.maven.settings.Settings instance is created.

3.4.1. About Maven mirror

Maven uses a set of remote repositories to access the artifacts, which are currently not available in local repository. The list of repositories almost always contains Maven Central repository, but for Red Hat Fuse, it also contains Maven Red Hat repositories. In some cases where it is not possible or allowed to access different remote repositories, you can use a mechanism of Maven mirrors. A mirror replaces a particular repository URL with a different one, so all HTTP traffic when remote artifacts are being searched for can be directed to a single URL.

3.4.2. Adding Maven mirror to settings.xml

To set the Maven mirror, add the following section to Maven’s settings.xml: 

<mirror>
      <id>all</id>
      <mirrorOf>*</mirrorOf>
      <url>http://host:port/path</url>
</mirror>

No mirror is used if the above section is not found in the settings.xml file. To specify a global mirror without providing the XML configuration, you can use either system property or environmental variables.

3.4.3. Setting Maven mirror using environmental variable or system property

To set the Maven mirror using either environmental variable or system property, you can add:

  • Environmental variable called MAVEN_MIRROR_URL to bin/setenv file
  • System property called mavenMirrorUrl to etc/system.properties file

3.4.4. Using Maven options to specify Maven mirror url

To use an alternate Maven mirror url, other than the one specified by environmental variables or system property, use the following maven options when running the application:

  • -DmavenMirrorUrl=mirrorId::mirrorUrl

    for example, -DmavenMirrorUrl=my-mirror::http://mirror.net/repository

  • -DmavenMirrorUrl=mirrorUrl

    for example, -DmavenMirrorUrl=http://mirror.net/repository. In this example, the <id> of the <mirror> is just a mirror.

3.5. About Maven artifacts and coordinates

In the Maven build system, the basic building block is an artifact. After a build, the output of an artifact is typically an archive, such as a JAR or WAR file.

A key aspect of Maven is the ability to locate artifacts and manage the dependencies between them. A Maven coordinate is a set of values that identifies the location of a particular artifact. A basic coordinate has three values in the following form:

groupId:artifactId:version

Sometimes Maven augments a basic coordinate with a packaging value or with both a packaging value and a classifier value. A Maven coordinate can have any one of the following forms: 

groupId:artifactId:version
groupId:artifactId:packaging:version
groupId:artifactId:packaging:classifier:version

Here are descriptions of the values:

groupdId
Defines a scope for the name of the artifact. You would typically use all or part of a package name as a group ID. For example, org.fusesource.example.
artifactId
Defines the artifact name relative to the group ID.
version
Specifies the artifact’s version. A version number can have up to four parts: n.n.n.n, where the last part of the version number can contain non-numeric characters. For example, the last part of 1.0-SNAPSHOT is the alphanumeric substring, 0-SNAPSHOT.
packaging
Defines the packaged entity that is produced when you build the project. For OSGi projects, the packaging is bundle. The default value is jar.
classifier
Enables you to distinguish between artifacts that were built from the same POM, but have different content.

Elements in an artifact’s POM file define the artifact’s group ID, artifact ID, packaging, and version, as shown here: 

<project ... >
  ...
  <groupId>org.fusesource.example</groupId>
  <artifactId>bundle-demo</artifactId>
  <packaging>bundle</packaging>
  <version>1.0-SNAPSHOT</version>
  ...
</project>

To define a dependency on the preceding artifact, you would add the following dependency element to a POM file: 

<project ... >
  ...
  <dependencies>
    <dependency>
      <groupId>org.fusesource.example</groupId>
      <artifactId>bundle-demo</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
  ...
</project>
Note

It is not necessary to specify the bundle package type in the preceding dependency, because a bundle is just a particular kind of JAR file and jar is the default Maven package type. If you do need to specify the packaging type explicitly in a dependency, however, you can use the type element.

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.