-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Fuse
Installation on Apache Karaf
Red Hat JBoss Fuse
Installing Red Hat JBoss Fuse on the Apache Karaf container
Red Hat
Version 6.3
Copyright © 2011-2020 Red Hat, Inc. and/or its affiliates.
27 Oct 2020
Abstract
It is easy to install Red Hat JBoss Fuse and tailor the installation to a particular environment.
Chapter 1. Installation Prerequisites
Abstract
Before attempting to install and use Red Hat JBoss Fuse, make sure your system meets the minimum requirements.
Supported platforms
Red Hat tests and supports Fuse products in the configurations listed at Red Hat JBoss Fuse Supported Configurations.
Java Runtime
For details of the Java runtimes supported by Red Hat JBoss Fuse, see Red Hat JBoss Fuse Supported Configurations.
Warning
Do not install the Java runtime under a directory path that includes whitespace. For example,
C:\Program Files\Java\jde7
is not an acceptable install path and will lead to unpredictable errors in Red Hat JBoss Fuse at run time.
Supported Standards
Red Hat JBoss Fuse supports the standards and protocols listed at Red Hat JBoss Fuse Supported Standards.
Hardware requirements
The minimum hardware requirements for installing Red Hat JBoss Fuse are:
- Full Installation
- 700 MB of free disk space
- 2 GB of RAM
In addition to the disk space required for the base installation, a running system will require space for caching, persistent message stores, and other functions.
Chapter 2. Installation Types
2.1. Overview of Installation Packages
Red Hat JBoss Fuse 6.3 is delivered in packages.
The standard install package is available for download from the Red Hat Customer Portal. It installs Apache Karaf, Apache Camel, Apache ActiveMQ, Apache CXF, SwitchYard, and the Fuse Management Console (Hawtio).
It is possible to create your own custom assembly of JBoss Fuse 6.3, containing a customized subset of the JBoss Fuse features and bundles. You can use this approach to replace the Minimal and the Medium install types, which were available for versions of JBoss Fuse prior to 6.2.
To create a custom assembly of JBoss Fuse, see Appendix C, Generating a Custom Assembly or an Offline Repository.
Chapter 3. Installing
Abstract
Red Hat JBoss Fuse is installed by unpacking an archive system on a system. This provides an easy way for a developer to get up and running.
Getting the archive
You can download the Red Hat JBoss Fuse archive from the Red Hat Customer Portal>Downloads>Red Hat JBoss Middleware>Downloads page, after you register and login to your customer account.
Once logged in:
- Select Fuse, listed under Integration Platforms, in the sidebar menu.
- Select
6.3
from the Version drop-down list on the Software Downloads page. - Click the Download button next to the Red Hat JBoss Fuse 6.3 on Karaf Installer file.
Unpacking the archive
Red Hat JBoss Fuse is packaged as a
.zip
file. Using a suitable archive tool, such as Zip, unpack Red Hat JBoss Fuse into a directory to which you have full access.
Warning
Do not unpack the 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\fusesrc
.
Warning
Do not unpack the archive file into a folder that has any of the following special characters in its path name:
#
, %
, ^
, "
.
Using the IBM JDK
If you are using the IBM JDK, remove the
saaj-api
jar from the installDir/lib/endorsed
library using the following command:
rm lib/endorsed/org.apache.servicemix.specs.saaj-api-1.3-2.7.0.jar
- Before invoking the
./bin/fuse
script:, set theJAVA_OPTS
environment variable as follows:JAVA_OPTS=-Xshareclasses:none
Installing Red Hat JBoss Development Tools
The JBoss Fuse development environment is included in JBoss Developer Studio starting with Developer Studio 11.0. After you download Developer Studio, see the Red Hat JBoss Developer Studio 11.0 Installation Guide. During installation, in the Select Additional Features to Install page, be sure to select JBoss Fuse Tooling.
Switchyard is included in JBoss Developer Studio Integration Stack. To install Switchyard tooling, see the Red Hat JBoss Developer Studio Integration Stack Installation Guide.
Chapter 4. Adding a Remote Console User
Abstract
The server's remote command console is not configured with a default user. Before you can connect to the server's console remotely, you must add a user to the configuration.
4.1. Add a User
Red Hat JBoss Fuse is not installed with a default user for the remote console. Before you can remotely manage a server, you must add a user by editing
InstallDir/etc/users.properties
.
Important
The information in this file is unencrypted so it is not suitable for environments that require strict security.
To add a user:
- Open
InstallDir/etc/users.properties
in your favorite text editor. - Locate the line
#admin=admin,admin,manager,viewer,Operator, Maintainer, Deployer, Auditor, Administrator, SuperUser
.This line specifies a useradmin
with the passwordadmin
and comma-separated list of roles. - Uncomment the line by removing the leading
#
. - Change the first
admin
to the desired user name. - Change the second
admin
to the desired password. - Leave the role list,
admin,manager,viewer,Operator, Maintainer, Deployer, Auditor, Administrator, SuperUser
, as is. - Save the changes.
Chapter 5. Offline Mode
Abstract
You can run the JBoss Fuse container in offline mode (that is, without an Internet connection). But 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.
5.1. Supported Functionality
If you want to run the JBoss Fuse container in offline mode, it is necessary to distinguish between the following kinds of dependency:
- Runtime dependencies—the dependencies required to run the JBoss Fuse container, in its default configuration.
- Build-time dependencies—the dependencies 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 JBoss Fuse container in its default configuration—is supported in offline mode. The default configuration of the JBoss Fuse container is specified by the
featuresBoot
property in theetc/org.apache.karaf.features.cfg
file. The requisite dependencies are all provided in thesystem/
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 thefeaturesRepositories
property in theetc/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, but in general, custom applications would have third-party dependencies that require an Internet connection (so that JAR files can be downloaded by Apache Maven).
If you do need to deploy an application with 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. This customized Maven offline repository can then be distributed internally to any machines that do not have an Internet connection. For more details of this approach, see section "Offline Repository for a Maven Project" in "Fabric Guide".
Chapter 6. Getting Started with SwitchYard on Apache Karaf
6.1. SwitchYard Overview
SwitchYard is a lightweight service delivery framework providing full lifecycle support for developing, deploying, and managing service-oriented applications.
It works with Apache Camel to provide a flexible integration runtime with comprehensive connectivity and transports.
SwitchYard tooling is provided with Red Hat JBoss Developer Studio Integration Stack. To install Switchyard tooling, see the Red Hat JBoss Developer Studio Integration Stack installation guide available from the customer portal.
Figure 6.1. SwitchYard Visual Editor
6.2. Installing SwitchYard on Apache Karaf
When a SwitchYard application is installed, its dependencies will be installed automatically as long as its
features
file is defined correctly.
You can test this by installing a quickstart application on a fresh installation of the JBoss Fuse Apache Karaf container.
You can also install SwitchYard and its related components manually.
Note
Each SwitchYard component and application is provided as a feature. Packaged features (including quickstart applications) are defined in the SwitchYard features file located at
installDir/system/org/switchyard/karaf/switchyard/2.1.0.redhat-630xxx/switchyard-2.1.0.redhat-630xxx-core-features.xml
.
Procedure 6.1. Install SwitchYard Manually
- Start the Apache Karaf container:
./bin/fuse
- List the available SwitchYard features by entering the following console command. If this is a fresh instance, they will all be uninstalled at this point.
JBossFuse:karaf@root> features:list | grep switchyard
- Install the core SwitchYard components by entering the following console command:
JBossFuse:karaf@root> features:install switchyard
- List the SwitchYard features again. You will now see that SwitchYard (the switchyard feature) has been installed, along with its dependencies as defined by the SwitchYard features file.
6.3. SwitchYard Quickstart Applications
You can find a variety of SwitchYard applications in
installDir/quickstarts/switchyard
.
Quickstart applications are typically installed from the Karaf command line console as follows:
- Start the Apache Karaf container:
./installDir/bin/fuse
- Install the application by entering the following console command:
JBossFuse:karaf@root> features:install switchyard-quickstart-APP_NAME
You can find out more about running each quickstart application by reading the accompanying
Readme.md
file for each.
Note
There is no need to add the features URL as described by the
Readme.md
file. SwitchYard features are already defined in installDir/system/org/switchyard/karaf/switchyard/2.1.0.redhat-630xxx/switchyard-2.1.0.redhat-630xxx-core-features.xml
.
6.4. Installing Your First Quickstart Application
The following procedure demonstrates how to install and run the
camel-quartz-binding
quickstart application. This application makes use of the camel-quartz
component which schedules a logging service to run every second.
- Start the Apache Karaf container:
./bin/fuse
- List the available SwitchYard features by entering the following console command. If this is a fresh instance, they will all be uninstalled at this point.
JBossFuse:karaf@root> features:list | grep switchyard
Install thecamel-quartz-binding
application by entering the following console command:JBossFuse:karaf@root> features:install switchyard-quickstart-camel-quartz-binding
- List the SwitchYard features again. You will now see that the camel-quartz-binding application (the switchyard-quickstart-camel-quartz-binding feature) has been installed, along with its dependencies as defined by the SwitchYard features file.
- View the output from the installed (and running) application by entering the following console command:
JBossFuse:karaf@root> log:tail
Note
Find out more about this quickstart application in
installDir/quickstarts/switchyard/camel-quartz-binding/Readme.md
.
6.5. What's Next?
Find out more about SwitchYard.
Appendix A. Installing the Apache Components
Abstract
Red Hat JBoss Fuse includes standard distributions of Apache Camel and Apache CXF in the installation's
extras
directory.
A.1. Zip Archives for the Apache Components
If you want to use a standard distribution of Apache Camel or Apache CXF, without the OSGi container or Fuse Fabric, use the archived versions in the installation's
extras
directory.
The following archives are provided for all supported platforms:
- apache-camel-2.17.0.redhat-630xxx.zip
- apache-cxf-3.1.5.redhat-630xxx.zip
You can 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\fusesrc
.
Appendix B. Red Hat JBoss Fuse Maven Repositories
Abstract
Red Hat JBoss Fuse strongly supports Maven, an open source build system available from Apache Maven. To use Maven to build your projects, you need to specify, in a Maven
settings.xml
file, where required artifacts are located.
For details on setting up Maven to work with Red Hat JBoss Fuse, see chapter "Building with Maven" in "Deploying into Apache Karaf".
B.1. Maven Repositories
The following repositories contain artifacts your projects may need:
- JBoss Fuse repositoryProvides access to the artifacts in the Red Hat Maven repository. This repository is required:
https://maven.repository.redhat.com/ga
- JBoss Fuse early access repositoryProvides access to the artifacts in the Red Hat Maven repository for early access releases. This repository is optional:
https://maven.repository.redhat.com/earlyaccess/all
Appendix C. Generating a Custom Assembly or an Offline Repository
Overview
The Karaf container in JBoss Fuse comes with a large collection of features installed by default. While this offers the advantage of a highly functional container, it requires a large amount of memory and resources. For some deployment scenarios, it can be an advantage to strip down the Karaf container to use the minimal set of features required for your application. A custom assembly is the most effective way to create a stripped down Karaf container that deploys only the features needed for your application.
The same procedure that is used to generate a custom assembly also generates an offline repository.
Custom assembly
A custom assembly is a custom distribution of the Karaf container based on JBoss Fuse, which is generated using a specific toolchain of Maven plug-ins. The quickstart examples include a template,
quickstart/custom
, which demonstrates how this toolchain works and provides you with the starting point for creating your own custom assemblies.
Note
A custom assembly is generated using essentially the same toolchain as the official JBoss Fuse Karaf container distribution.
Patched custom assembly
If your starting point is a JBoss Fuse rollup patch (which is, in fact, equivalent to a complete distribution of the JBoss Fuse product with patches already applied), and you then follow the steps for generating a custom assembly, what you end up with is a patched custom assembly. No actual patching step needs to be performed in this case, however, because the patch is already built-in to the custom assembly.
Offline repository
An
offline repository
is a Maven repository that contains a custom collection of Maven artifacts that would otherwise need to be downloaded from the Internet. For JBoss Fuse deployments that lack Internet access, the offline repository makes it possible to run the container in an isolated network by providing all of the Maven artifacts that your application might need. For details about how to install an offline repository in a standalone Karaf container, see chapter "Locating Artifacts with Maven and HTTP" in "Deploying into Apache Karaf".
quickstart/custom example
The
quickstart/custom
example provides a template for generating your own custom assembly. The default configuration of the custom example includes a very minimal collection of Karaf features. You can easily customize this configuration to specify example which Karaf features you would like to include in the custom assembly.
Procedure to generate a custom assembly or an offline repository
To generate a custom assembly, or a patched custom assembly, or an offline Maven repository, perform the following steps:
- Choose the appropriate starting point for this procedure:
- To generate a custom assembly—download and install the standard install from the Red Hat Customer Portal, as described in Chapter 3, Installing; or
- To generate a patched custom assembly—download the latest rollup patch from the Red Hat Customer Portal.
- Go to the
InstallDir/quickstarts/custom
project. - Customize the features that will be included in the custom assembly's
system/
directory (or in the generated offline repository) by editing the project'spom.xml
file. Thepatch
feature and thefabric
feature are both required, and must be added to the configuration.Open thequickstarts/custom/pom.xml
file in a text editor, search for thefeatures-maven-plugin
plug-in configuration, and add thepatch
feature and thefabric
feature as children of theconfiguration/features
XML element—for example:<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> ... <build> <plugins> ... <!-- Step 3: gather all the bundles for the features your want to install --> <plugin> <groupId>org.apache.karaf.tooling</groupId> <artifactId>features-maven-plugin</artifactId> <version>2.4.1</version> <executions> <execution> <id>add-features</id> <goals> <goal>add-features-to-repo</goal> </goals> <phase>generate-resources</phase> <configuration> ... <features> <!-- TODO: add the feature you want to use in your custom assembly to the list below --> <feature>shell</feature> <feature>admin</feature> <feature>management</feature> <feature>camel-blueprint</feature> <feature>camel-jaxb</feature> <feature>patch</feature> <feature>fabric</feature> </features> <repository>target/repository</repository> </configuration> </execution> </executions> ... </plugin> ... </plugins> </build> ... </project>
- (Not required for an offline repository) Customize the list of features that will be installed automatically when the custom assembly's container first starts. The
patch
feature and thefabric
feature are both required, and must be added to this list.Open thesrc/main/filtered-resources/etc/org.apache.karaf.features.cfg
file and modify thefeaturesBoot
property setting as required, adding at least thefabric
feature and thepatch
feature to the list:... # TODO: list the boot features for your own assembly below featuresBoot=shell,admin,management,fabric,patch,camel-blueprint,camel-jaxb
- Install the JBoss Fuse distribution into your local Maven repository. In the following example, you would replace xxx with the version number in your artifact:
mvn install:install-file \ -Dfile=/path/to/fuse/jboss-fuse-karaf-6.3.0.redhat-xxx.zip \ -DgroupId=org.jboss.fuse \ -DartifactId=jboss-fuse-karaf \ -Dversion=6.3.0.redhat-xxx \ -Dpackaging=zip \ -DgeneratePom=false
- After customizing the configuration of the
quickstarts/custom
project, build the project as follows:mvn clean package
- The offline repository is now available in the following directory:
InstallDir/quickstarts/custom/target/repository
If the purpose of this build is to create an offline repository, the procedure is now finished and you can skip the remaining steps. - The result of building this project is a custom assembly file, in the following location:
InstallDir/quickstarts/custom/target/custom-distro-ProductVersion-bin.zip
- The custom assembly requires some additional modifications. In preparation for this, unpack the custom assembly file,
custom-distro-ProductVersion-bin.zip
, into a convenient working location on the file system:Working/custom-distro-ProductVersion-bin
- To reduce the size of the custom assembly, delete the
extras/
subdirectory fromcustom-distro-ProductVersion-bin
(saving about 67 MB). - Create a new baseline archive for the custom assembly, as follows:
- Make a copy of the entire
Working/custom-distro-ProductVersion-bin
directory, to give a copy like the following:Working/custom-distro-ProductVersion-bin(copy)
- Rename the copied directory,
custom-distro-ProductVersion-bin(copy)
, to the following:jboss-fuse-karaf-ProductVersion-baseline
For example, if theProductVersion
is 6.3.0.redhat-xxx, the new directory name must bejboss-fuse-karaf-6.3.0.redhat-xxx-baseline
. - Delete the
system/
subdirectory from thejboss-fuse-karaf-ProductVersion-baseline
directory. In addition, if any of the following subdirectories are present, they can also be deleted (as they are not needed in the baseline):data/ deploy/ extras/ quickstarts/
- Using an archive tool, compress the
jboss-fuse-karaf-ProductVersion-baseline
directory in Zip format to give the following archive file:jboss-fuse-karaf-ProductVersion-baseline.zip
The preceding file is the baseline archive for the custom assembly.
- Copy the baseline archive to the following subdirectory (must be created) of the original custom assembly,
Working/custom-distro-ProductVersion-bin
:system/org/jboss/fuse/jboss-fuse-karaf/ProductVersion
- The custom assembly,
Working/custom-distro-ProductVersion-bin
, is now complete. If you like, you can compress this directory into a Zip archive and distribute it as is. - Test the new custom assembly to make sure it is working properly. Launch the Karaf container, as follows:
cd Working/custom-distro-ProductVersion-bin/bin ./fuse
The container should start up without error. To make sure that no errors have occurred, check the log:JBossFuse:karaf@root> log:display
You can also check to see whether all of the expected Karaf features are installed:JBossFuse:karaf@root> features:list -i
When you are finished testing the custom assembly container, shut it down by entering theshutdown
console command, and tidy up the custom assembly installation by removing thedata/
subdirectory (which holds the data from the current container instance).
Troubleshooting
There are a few common errors you might encounter when attempting to start the custom assembly container. Here is a brief explanation of what these errors mean:
- The following error indicates that the baseline archive was not correctly installed in the
system
directory:ERROR: Bundle org.apache.felix.framework [0] EventDispatcher: Error during dispatch. (io.fabric8.patch.management.PatchException: Can't find baseline distribution in patches dir or inside system repository.) io.fabric8.patch.management.PatchException: Can't find baseline distribution in patches dir or inside system repository. at io.fabric8.patch.management.impl.GitPatchManagementServiceImpl.trackBaselineRepository(GitPatchManagementServiceImpl.java:1820) at ...
- The following error indicates that the
patch
feature is not deployed in the container:Bundle listed in startup.properties configuration not found: io/fabric8/patch/patch-management/1.2.0.redhat-621092/patch-management-1.2.0.redhat-621092.jar Could not create framework: java.lang.Exception: Aborting due to missing startup bundles java.lang.Exception: Aborting due to missing startup bundles at org.apache.karaf.main.Main.processConfigurationProperties(Main.java:1281) at org.apache.karaf.main.Main.loadStartupProperties(Main.java:1082) at org.apache.karaf.main.Main.launch(Main.java:346) at org.apache.karaf.main.Main.main(Main.java:561)
- The following error indicates that the
patch
feature was successfully deployed, but the requiredfabric
feature is missing:ERROR: Bundle io.fabric8.patch.patch-core [49] Error starting mvn:io.fabric8.patch/patch-core/1.2.0.redhat-621092 (org.osgi.framework.BundleException: Unresolved constraint in bundle io.fabric8.patch.patch-core [49]: Unable to resolve 49.0: missing requirement [49.0] osgi.wiring.package; (&(osgi.wiring.package=io.fabric8.api)(version>=1.2.0)(!(version>=2.0.0))))
Legal Notice
Trademark Disclaimer
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, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Apache, ServiceMix, Camel, CXF, and ActiveMQ are trademarks of Apache Software Foundation. Any other names contained herein may be trademarks of their respective owners.