Deployed and running in under 2 minutes...

This article is intended to illustrate quite how easy it is to deploy BlackTie onto a fresh machine. We will also be running all the examples that ship with BlackTie in this article using a simple automated script (it may take a little of the fun of exploration out of it but you can always go back and run them by hand).

Watch this on Vimeo!

NOTE: THIS VIDEO APPLIES TO VERSION 2 OF BLACKTIE - UPDATE COMING SOON!

You can watch us on Vimeo doing the install:

Deploying BlackTie from Tom Jenkinson on Vimeo.

Prerequisites

In order to deploy BlackTie and run the examples you will need to install a few pieces of software - this isn't included in the 2 minutes!

To check that you have installed the items correctly, you can run a "-version" command on each of these:

java -version

java version "1.6.0_20"

Java(TM) SE Runtime Environment (build 1.6.0_20-b02)

Java HotSpot(TM) 64-Bit Server VM (build 16.3-b01, mixed mode)

ant -version

Apache Ant version 1.7.1 compiled on June 27 2008

mvn -version

Apache Maven 2.2.1 (r801777; 2009-08-06 20:16:01+0100)

Java version: 1.6.0_20

Java home: /usr/java/jdk1.6.0_20/jre

Default locale: en_US, platform encoding: UTF-8

OS name: "linux" version: "2.6.35.10-74.fc14.x86_64" arch: "amd64" Family: "unix"

You will also need

The following software is what we would consider to be "BlackTie" and so you will need to obtain these two items, dependending on your browsing speed you can maybe include these in the two minutes, but you would need to be quick!

Start your watches!

Installing JBoss Application Server 5.1.0.GA

1. Extract the JBoss AS compressed file into any location on your hard drive, this location will now be referred to as <JBOSS_HOME>

Installing Hornet Q into JBoss AS

1. Extract the HornetQ compressed file into any location on your hard drive, this location will now be referred to as <HQ_HOME>
2. cd <HQ_HOME>/config/jboss-as-5/
3. chmod 775 build.sh
4. export JBOSS_HOME=<JBOSS_HOME> && ./build.sh && export JBOSS_HOME=
5. Edit <JBOSS_HOME>/server/all-with-hornetq/deploy/hornetq.sar/hornetq-configuration.xml

        Replace:

</security-settings>

        With:

     <security-setting match="jms.queue.BTR_BTDomainAdmin">\

         <permission type="send" roles="blacktie,guest"/>\

         <permission type="consume" roles="blacktie,guest"/>\

      </security-setting>\

      <security-setting match="jms.queue.BTR_BTStompAdmin">\

         <permission type="send" roles="blacktie,guest"/>\

         <permission type="consume" roles="blacktie,guest"/>\

      </security-setting>\

</security-settings>

6. Edit <JBOSS_HOME>/server/all-with-hornetq/deploy/hornetq.sar/hornetq-jms.xml

        Replace:

<connection-factory name="InVMConnectionFactory">

        With:

<connection-factory name="InVMConnectionFactory">

      <consumer-window-size>0</consumer-window-size>

7. Edit <JBOSS_HOME>/server/all-with-hornetq/deploy/hornetq.sar/hornetq-jms.xml

       Replace:

<connection-factory name="InVMConnectionFactory">

       With:

<connection-factory name="InVMConnectionFactory">

      <connection-ttl>-1</connection-ttl>

      <client-failure-check-period>86400000</client-failure-check-period>

8. Edit <JBOSS_HOME>/server/all-with-hornetq/deploy/hornetq-ra.rar/META-INF/ra.xml

       Replace:

<resourceadapter-class>org.hornetq.ra.HornetQResourceAdapter</resourceadapter-class>

       With:

<resourceadapter-class>org.hornetq.ra.HornetQResourceAdapter</resourceadapter-class>

 

      <config-property>

        <description>The connection TTL</description>

        <config-property-name>ConnectionTTL</config-property-name>

        <config-property-type>java.lang.Long</config-property-type>

        <config-property-value>-1</config-property-value>

      </config-property>

      <config-property>

        <description>The client failure check period</description>

        <config-property-name>ClientFailureCheckPeriod</config-property-name>

        <config-property-type>java.lang.Long</config-property-type>

        <config-property-value>86400000</config-property-value>

      </config-property>

Installing JTS into JBoss AS

1. cd <JBOSS_HOME>/docs/examples/transactions
2. Type: ant jts -Dtarget.server.dir=../../../server/all-with-hornetq
3. Edit <JBOSS_HOME>/server/all-with-hornetq/conf/jbossts-properties.xml to change the CONFIGURATION_FILE to NAME_SERVICE

NOTE: If you are intending to run JBoss any other address than   localhost you will need to replace all references of localhost in the config file <JBOSS_HOME>/server/all/conf/jacorb.properties to  the IP address parameter you start JBoss AS on in the run.sh -b command below

Installing JBossESB into JBoss AS

1. copy jboss-as-hornetq-int.jar to <JBOSS_HOME>/common/lib
2. copy hornetq-deployers-jboss-beans.xml to <JBOSS_HOME>/server/all-with-hornetq/deployers
3. cd jbossesb-[version]/install
4. update deployment.properties to point to JBossAS installation
   org.jboss.esb.server.home=/jboss-5.1.0.GA
   org.jboss.esb.server.config=all-with-hornetq
5. update build.xml and add hornetq.sar to the messaging providers to detect
   <available property="hornetq.present" file="${deploy.dir}/hornetq.sar"/>
6. ant deploy

Installing JBoss Blacktie

1. Extract the blacktie-[version]-bin.zip|tar.gz into any location on your hard drive - this location will now be referred to as BLACKTIE_BIN_DIR
2. Copy <BLACKTIE_BIN_DIR>/blacktie-admin-services/stompconnectservice-ear-[VERSION].ear to <JBOSS_HOME>/server/all-with-hornetq/deploy/
3. We will now deploy the blacktie-admin-services.
   1. As .ear files do not contain the top level folder within them, you will need to create this to extract it into for the blacktie-admin-services as this ear must be deployed "exploded"
   2. mkdir <JBOSS_HOME>/server/all-with-hornetq/deploy/blacktie-admin-services-ear-[VERSION].ear/
   3. Unzip <BLACKTIE_BIN_DIR>/blacktie-admin-services/blacktie-admin-services-ear-[VERSION].ear to <JBOSS_HOME>/server/all-with-hornetq/deploy/blacktie-admin-services-ear-[VERSION].ear/
   4. If you are intending to run JBoss any other address than localhost you will need to replace all references of localhost in the file <JBOSS_HOME>/server/all-with-hornetq/deploy/blacktie-admin-services-ear-[VERSION].ear/btconfig.xml to the IP address parameter you start JBoss AS on)
4. Copy <BLACKTIE_BIN_DIR>/blacktie-admin-services/blacktie-rhq-plugin-[VERSION].jar to <JBOSS_HOME>/server/all-with-hornetq/deploy/admin-console.war/plugins
5. Edit <BLACKTIE_BIN_DIR>/setenv.sh|bat to enter the location of BLACKTIE_BIN_DIR
6. Edit <BLACKTIE_BIN_DIR>/setenv.sh|bat to set the hostname you have started JBoss on as JBOSSAS_IP_ADDR

Start JBoss

1. Cd to <JBOSS_HOME>/bin
2. Execute: run.[sh|bat] -c all-with-hornetq -b localhost

NOTE: if you are on AIX you will also need to add: -Djava.net.preferIPv4Stack=true as run.sh only special cases linux in that respect

NOTE: If you are intending to run JBoss any other address than  localhost you will need to replace all references of localhost in the blacktie config file <JBOSS_HOME>/server/all/conf/btconfig.xml to the IP address parameter you start JBoss AS on here

Configuring the Examples

Out of the box, the examples need their configuration tweaking in order to specify the hostname and install location of BlackTie.

The following files need to be updated

<BLACKTIE_BIN_DIR>/examples/admin/jmx/src/test/java/org/jboss/blacktie/examples/jmx/*.java"/>

<BLACKTIE_BIN_DIR>/examples/integration1/ejb/ear/pom.xml"/>

<BLACKTIE_BIN_DIR>/examples/integration1/xatmi_adapter/ear/pom.xml"/>

<BLACKTIE_BIN_DIR>/examples/integration1/xatmi_adapter/src/main/resources/btconfig.xml"/>

<BLACKTIE_BIN_DIR>/examples/mdb/src/main/resources/btconfig.xml"/>

1. Open each of the files
2. Replace the text localhost with the parameter you start JBoss listening on passed to JBoss in the run.sh|bat -b parameter
3. Replace the text REPLACE_WITH_INSTALL_LOCATION with the fully qualified pathname referred to by <BLACKTIE_BIN_DIR>

Running the Examples

1. Cd to <BLACKTIE_BIN_DIR>
2. Source the setenv.[sh|bat] script
3. Execute the samples script run_all_samples.[sh|bat]

NOTE: These examples assume that you are running with IPv4 if not, please edit the btconfig.xml files as shown in running the examples by hand below

NOTE: The run_all_samples.[sh|bat] script does not run the txfooapp database example, you will need to build and run this example by hand (see following section for general information)

Stop the clock!

Next Steps: Build and run the examples by hand

Change directory to <BLACKTIE_BIN_DIR>/examples/xatmi/fooapp and follow the README

Then, leaving the server running, follow the instructions in <BLACKTIE_BIN_DIR>/examples/jab/fooapp.

Finally (after killing the server started above), follow the instructions in <BLACKTIE_BIN_DIR>/examples/mdb

NOTE: If you are using IPv6 you will need to edit the btconfig.xml files to change the word localhost to localhost4

NOTE: The M2 README is out of date slightly, replace the word stompconnectservice with blacktie-admin-services when following the instructions in the README, you will also need to copy the btconfig.xml from the blacktie-admin-services folder to <JBOSS_HOME>/server/all/conf/ as above

Next Steps: Further reading

Once you are comfortable with running the examples, you will probably want to check out the following article which describes how to build the services and clients using our build tools:

Building XATMI services and clients

If you want to run blacktie server or client on the different hosts, you will want to check out the following article:

Running BlackTie with a different host IP address

To use the monitoring and management capabilities of a blacktie server, you will want to check out:

Monitoring and management of blacktie servers by blacktie-rhq-plugin