Ce contenu n'est pas disponible dans la langue sélectionnée.
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/customproject. - 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.xmlfile. Thepatchfeature and thefabricfeature are both required, and must be added to the configuration.Open thequickstarts/custom/pom.xmlfile in a text editor, search for thefeatures-maven-pluginplug-in configuration, and add thepatchfeature and thefabricfeature as children of theconfiguration/featuresXML 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
patchfeature and thefabricfeature are both required, and must be added to this list.Open thesrc/main/filtered-resources/etc/org.apache.karaf.features.cfgfile and modify thefeaturesBootproperty setting as required, adding at least thefabricfeature and thepatchfeature 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/customproject, 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-bindirectory, 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 theProductVersionis 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-baselinedirectory. 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-baselinedirectory 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 theshutdownconsole 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
systemdirectory: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
patchfeature 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
patchfeature was successfully deployed, but the requiredfabricfeature 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))))
