After downloading the ZooKeeper release archive, choose a location where it will reside. It is possible to utilize a single server node to host both A-MQ and ZooKeeper. However, in order to facilitate similarities to likely production environments, this document assumes separate server clusters for each technology. The root installation location used herein for ZooKeeper is /opt/zookeeper_3.4.8/.

Heap memory available to each ZooKeeper instance can be configured via creating a file in the conf directory called java.env containing the following text:

export JVMFLAGS="-Xms2G -Xmx3G"

The data directory and port of usage utilized by ZooKeeper are likewise specified in a file within the conf directory called zoo.cfg:

clientPort=2181
dataDir=/opt/zookeeper_3.4.8/data
syncLimit=5
tickTime=2000
initLimit=10
dataLogDir=/opt/zookeeper_3.4.8/data
server.1=zk1:2888:3888
server.2=zk2:2888:3888
server.3=zk3:2888:3888

The minimum number of nodes suggested for a ZooKeeper ensemble is three instances, thus the server entries seen above, where 'zk[1-3]' are host entries aliasing the local network IP addresses of each ZooKeeper server. Each node within an ensemble should use an identical copy of the zoo.cfg file. Note the ports 2888 and 3888 given above, which in addition to the clientPort of 2181, allow for quorum and leader elections and thus may require firewall configuration on your part to ensure availability. If you desire to run multiple ZooKeeper instances on a single machine, rather than on three separate servers as done herein, each server instance should have a unique assignment of these two ports (2888:3888, 2889:3889, 2890:3890, etc).

Sample copies of both java.env and zoo.cfg have been included in the accompanying attachment file under the /config_files/zookeeper/ directory.

Once configured, the ZooKeeper instance can be started via the [install_dir]/bin directory with the following command:

# ./zkServer.sh start

You can tail the instance’s log file with the following command:

# tail -f [root_install_dir]/zookeeper.out

For further information on configuring, running, and administering ZooKeeper instances and ensembles, please refer to the Apache Zookeeper Getting Started Guide and Administrator’s Guide.

After downloading Red Hat JBoss A-MQ 6.2.1, choose a location where it will reside. The root installation location used herein for A-MQ is /opt/amq_6.2.1/.

Prior to starting the instance, further configuration is required for utilizing the replicated LevelDB store strategy. Should you choose to use a different persistence strategy, now is the time to configure it as detailed in the Red Hat JBoss A-MQ Guide to Configuring Broker Persistence. To follow along with the strategy adhered to within, proceed as follows:

First step is to ensure that your system has at least one user set up. Open the file [root_install]/etc/users.properties and ensure that at least an admin user is present and not commented out:

# You must have at least one users to be able to access JBoss A-MQ resources

*admin=admin,admin,manager,viewer,Operator, Maintainer, Deployer, Auditor, Administrator, SuperUser*

If you would like to verify the basic installation of A-MQ at this time, steps for doing so can be found in the Red Hat A-MQ Installation Guide under the heading Verifying the Installation.

Next, configure the persistence mechanism by editing the [root_install]/etc/activemq.xml file to include the <persistenceAdapter> section as shown below:

Note that the binding is unique to the network interface IP address of the specific node, while the zkAddress will be identical across all A-MQ instances. The number of replicas should reflect the number of nodes within your ZooKeeper ensemble.

The last step in configuring the A-MQ instance involves editing the [root_install]/bin/setenv script file. Inside, you can specify the amount of Heap space available to the instance, as well as exporting a JVM arg called SERIALIZABLE_PACKAGES:

#!/bin/sh
...
if [ "$KARAF_SCRIPT" = "start" ]; then
    JAVA_MIN_MEM=2G
    JAVA_MAX_MEM=3G
    export JAVA_MIN_MEM # Minimum memory for the JVM
    export JAVA_MAX_MEM # Maximum memory for the JVM
fi
...
export KARAF_OPTS="-Dorg.apache.activemq.SERIALIZABLE_PACKAGES=\"*\""

The SERIALIZABLE_PACKAGES is related to HACEP’s usage of the ObjectMessage, which depends on Java [de]serialization to [un]marshal object payloads. Since this is generally considered unsafe, given that payloads could exploit the host system, the above option can be tuned to be more specific to those object types which we know the system will be dealing with. For more details on ObjectMessage, refer to the relevant ActiveMQ documentation. A more finely-tuned example would read as follows:

export KARAF_OPTS="-Dorg.apache.activemq.SERIALIZABLE_PACKAGES=\"it.redhat.hacep,com.redhat.refarch.hacep,your.company.model.package\""

After configuration is complete, you can start the A-MQ instance by issuing the following command from the [root_install]/bin/ directory:

# ./start

You can tail the instance’s log file with the following command:

# tail -f [root_install_dir]/data/log/amq.log

At this point, your replicated A-MQ Event Channel is now fully established and running, ready to feed events to the HACEP framework integration application.

Given that HACEP requires, at a minimum, two clustered instances, EAP installations in a production environment will likely result in use of domain clustering functionality. However, given the documentation necessary to effectively cover active/passive clustering appropriate for a production environment, the reader is instead encouraged to utilize the Red Hat Reference Architecture for Configuring a JBoss 7 EAP Cluster when establishing production-ready environments. In order to maintain focus on the integration and functionality of the HACEP framework in a proof-of-concept environment, two separate EAP standalone server instances are used herein, allowing JGroups to do the inter-node communication necessary for HACEP to function.

java -jar jboss-eap-7.0.0-installer.jar

[ Console installation done ]

4.3.3.2. Patch Application

With basic installation complete, start the server in standalone mode in order to apply the 7.0.1 patch file by issuing the following command:

[root_install_dir]/bin/standalone.sh -b 0.0.0.0 -bmanagement 0.0.0.0

Note that in the lines above, an IP binding of 0.0.0.0 is provided for both the server & management ports of the address, which in most environments allows the server to listen on all available interfaces. If you’ve chosen to run installations across various virtual machines, you may also find these parameters necessary to allow configuring the server away from localhost.

Once the server has started, you can access the management UI interface at http://[ip_address]:9990 with the credentials supplied during installation. From the landing page, you can then select Apply a Patch in the bottom-left to start the patching process. Provide the downloaded patch file when requested, then complete the process. Following completion, stop the standalone server.

Figure 4.1. EAP Management UI Landing Page

13:11:43,390 INFO  [org.jboss.as.connector.deployment] (MSC service thread 1-1) WFLYJCA0002: Bound JCA AdminObject [java:/queue/hacep-facts]

13:11:43,390 INFO  [org.jboss.as.connector.deployment] (MSC service thread 1-1) WFLYJCA0002: Bound JCA ConnectionFactory [java:/HacepConnectionFactory]

13:11:43,430 INFO  [org.jboss.as.server] (ServerService Thread Pool -- 35) WFLYSRV0010: Deployed "activemq-rar.rar" (runtime-name : "activemq-rar.rar")