Deploying Blacktie

Version 63

    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!

    NameWhere to obtain
    Java 1.6.0_20http://java.sun.com/javase/downloads/index.jsp
    Ant 1.7.1http://archive.apache.org/dist/ant/binaries/
    Maven 2.2.1http://archive.apache.org/dist/maven/binaries/

    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!

    NameWhere to obtain
    JBoss 5.1.0.GA
    http://www.jboss.org/jbossas/downloads/
    HornetQ 2.1.2http://www.jboss.org/hornetq/downloads.html
    JBossESB 4.9http://www.jboss.org/jbossesb/downloads
    BlackTie X.x.x.YY
    http://www.jboss.org/blacktie/downloads.html

    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
    6.         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>

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

      <connection-factory name="InVMConnectionFactory">

              With:

      <connection-factory name="InVMConnectionFactory">

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

    9. Edit <JBOSS_HOME>/server/all-with-hornetq/deploy/hornetq.sar/hornetq-jms.xml
    10.        Replace:

      <connection-factory name="InVMConnectionFactory">

             With:

      <connection-factory name="InVMConnectionFactory">

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

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

    11. Edit <JBOSS_HOME>/server/all-with-hornetq/deploy/hornetq-ra.rar/META-INF/ra.xml
    12.        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