This article describes how to cluster Geronimo HTTP Session web application data using the Open Terracotta project.

Open Terracotta Overview

Open Terracotta is an OSS project that supports transparent clustering. The project currently has three different packages available:

• Clustering POJOs (Terracotta DSO Package)
• Terracotta HTTP Session Clustering (Terracotta Sessions Package)
• Terracota for Clustering Spring (Terracotta Spring Package)

This article will utilize the Terracotta Sessions Package to cluster HTTP Sessions in the Geronimo environment.

Here are some of the highlights of the Open Terracotta technology:

• Application developers no longer needs to write their application for a clustered environment
• Clustering is transparently done at runtime via JVM level clustering (byte code instrumentation of JVM)
• The Terracotta Sever is responsible for transparently replicating/maintaining state across all application servers in the cluster
• Cluster Members appear to be part of one large Global JVM
• Terracotta Clustering does not require "Data Serialization"
• Developers define (in xml configuration file) which objects are to clustered. For the Terracotta Sessions package this includes identifying which context-roots are to be clustered as well as the data types that are to be placed in the HttpSession
• Terracotta supports ACID (Atomic, Consistent, Isolated, Durable) Compliance (transactional behavior between cluster members)
• Open Terracotta supports lazy loading across cluster members
  
  

More information on the Open Terracotta project available at: http://wiki.terracotta.org/confluence/display/orgsite/Home

Article Overview

This article documents how to cluster a simple web application's HttpSession data using Open Terracotta. The required steps include:

• Install Terracotta Server
• Install Geronimo Server
• Install Terracotta Client
• Update Terracotta configuration file
• Start Terracotta Server
• Start Terracotta Client and Geronimo Server
• Install Web Application on each Geronimo cluster member
• Setup Load Balancing and Failover
• Testing Load Balancing and Failover
• Use the Terracotta admin console

Install Terracotta Server installterracotta

Terracotta needs to be installed on one machine that will serve as the Terracotta Server. The Terracotta server will be responsible for maintaining session state and assuring that it is accurately reflected in each of the Geronimo cluster members.

Download the Terracotta Sessions bundle and run the Installer. This example requires "Open Terracotta 2.2.1 Stable 2" or higher.

Install Geronimo Serverinstallgeronimo

The Geronimo Application Server needs to be installed on each machine that is to be clustered. The example in this article will install Geronimo on two separate machines (cluster members).

Download the Geronimo image that includes the Tomcat web container from the Geronimo Website and unpack it on each of the cluster members. This example requires Geronimo 1.1.1 with the Tomcat web container. The Jetty web container is not yet supported by Terracotta.

Install Terracotta Clientinstallterracottaclient

The Terracotta client needs to be installed on each machine that contains a Geronimo cluster member. Currently, the same install bundle includes both the Terracotta server and client. So, it is possible to run the Terracotta Server and Terracotta Client on the same machine with a common installation .

Download the Terracotta Sessions bundle and run the Installer on each cluster member. This example requires "Open Terracotta 2.2.1 Stable 2" or higher.

Update Terracotta configuration file configtc

The tc-config.xml file identifies which context-roots are to be clustered as well as the data types that are to be placed in the HttpSession.

This example will use the Terracotta configuration file that is delivered with the Terracotta distribution. The specific file is: C:\Terracotta\terracotta-2.2.1\sessions\sandbox\tomcat5.5\tc-config.xml

Change the tc-config.xml file to look similar to the following example. Note that the tc-config.xml example below only shows the xml items that are to be updated. Other portions of that xml file should remain unchanged. Remember to change the IP address in the example below to the address of the Terracotta Server.

Start Terracotta Server starttc

Start the Terracotta server specifying the location of the tc-config.xml file that you just updated.

• cd C:\Terracotta\terracotta-2.2.1\sessions\bin
• start-tc-server.bat -f c:\Terracotta\terracotta-2.2.1\sessions\sandbox\tomcat5.5\tc-config.xml

Start Terracotta Client and Geronimo Serverstartgeronimo

Open Terracotta supports a variety of JVMs and each one requires a unique boot jar be present in the bootclasspath when launching the Geronimo server. The example below is using the Windows JVM that is present in the Terracotta Sessions Package. It is possible to use other JVMs, though a different boot jar will likely need to be created. Also some of the launch arguments in the script below were obtained by issuing the dso-env script in c:\Terracotta\terracotta-2.2.1\sessions\bin\ directory. You should issue this command on your system to find the arguments that are appropriate for your environment.

The IPAddress in the example below needs to be replaced with the IP Address (or hostname) of your Terracotta server. This value will be used to determine which Terracotta server will provide the Terracotta client with its tc-config.xml file. Alternately, -Dtc.config="IPAddress:9510" can be ommitted though you will need to update tc-config.xml on each cluster member (e.g. c:\Terracotta\terracotta-2.2.1\sessions\sandbox\tomcat5.5\tc-config.xml). Review the Terracotta documentation for more details.

Here is an example startup on a Windows Machine:

Install Web Application on each Geronimo cluster member installapp

Use the Geronimo admin console to install the appropriate example application to each of the Geronimo installations.

Here are links to the example applications and the deployment plan.

• servlets-examples-cluster-node1.war - Web application for Cluster Member 1
• servlets-examples-cluster-node2.war - Web application for Cluster Member 2
• servlets-examples-geronimo-plan.xml - Geronimo common deployment plan (for both cluster members)

Note that the two applications above are identical except for the field which indicates the Server name (e.g. Server1, Server2). This distinction will be useful when testing.

• The Geronimo admin console can be accessed at http://localhost:8080/console on each machine.
• The default id and password for the Geronimo admin console is id=system password=manager.
• Select "Applications-> Deploy New" from the GUI and follow the instructions on the panel for installing the example application

Now test that the applications were deployed correctly by accessing the applications with your favorite Web Browser:

http://YourHost1:8080/servlets-examples-terracotta/servlet/SessionExample
http://YourHost2:8080/servlets-examples-terracotta/servlet/SessionExample

If this is working correctly, it is now time to setup the Load Balancer.

Setup Load Balancing and Failoverinstallwebserver

Now you are ready to setup the Load Balancer. We recommend using Apache HTTP server and mod_jk for this example.

• Install Apache HTTP server - instructions and downloads available at http://httpd.apache.org/
• Install Apache mod_jk - See http://tomcat.apache.org/tomcat-5.5-doc/balancer-howto.html

Configuration tips for mod_jk:

worker.list=loadbalancer,status
worker.node1.port=8009
worker.node1.host=_your.first.cluster.member.host.name_or_IP_address
worker.node1.type=ajp13
worker.node1.lbfactor=1

worker.node2.port=8009
worker.node2.host=_your.second.cluster.member.host.name_or_IP_address
worker.node2.type=ajp13
worker.node2.lbfactor=1

worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
worker.loadbalancer.sticky_session=1
worker.status.type=status

/servlets-examples-terracotta=loadbalancer
/servlets-examples-terracotta/*=loadbalancer

Testing Load Balancing and Failovertest

Once you get Apache HTPP Server and mod_jk setup correctly. You can test load balancing and failover by requesting the following URL with your favorite Web browser. Of course, replace YourHost with the actual host name or IP address.

http://YourHost/servlets-examples-terracotta/servlet/SessionExample

Note that the output page contains the ID of the server that is servicing the request. In your browser window, fill in the appropriate input fields and hit the submit button. Add a few more items to your shopping cart. Notice that the browser indicates which server (Server1 or Server2) is servicing your request. Without Sticky Session support, you may see the load balancer alternately route the requests between the two cluster members. If you have setup everything correctly, then the shopping cart data should be present in the session after the browser request moves between the two servers. For Sticky Session, you can test failover by stopping the geronimo server that is currently servicing the session and seeing that the next http request will failover into the remaining cluster member. The httpsession data from the previous request should be recovered and displayed in the refreshed browser window.

Use the Terracotta admin consoletcadmin

The Terracotta Admin console can also be used to verify that session data is being properly replicated in the Terracotta Server.

Issue the Following commands

• cd c:\Terracotta\terracotta-2.2.1\sessions\bin
• tc-admin.bat
• Specify port 9520 and select "Connect"
• Navigate down through the resource tree and you will be able to see the httpSession data from your browser!
  
  

Investigation Items (can possibly become FAQ in near future)

• Investigate if there is a slimmed down Terracotta sessions download image that doesn't include the Session Configurator, JDK, samples, etc.
• Investigate if there is a slimmed down Terracotta sessions download image that includes only the Terracotta Client.
• Investigate if Open Terracotta plans to support the Jetty Web Container.
• Investigate Sticky Session support.
• Investigate when Open Terracotta will support EJB clustering for Geronimo.
• Investigate when Open Terracotta will support the IBM JDK.