Jetty has moved!
Jetty is a project at the Eclipse Foundation.
Homepage:http://www.eclipse.org/jetty
Downloads: http://download.eclipse.org/jetty/
Documentation:http://www.eclipse.org/jetty/documentation/current/
About:http://www.eclipse.org/jetty/about.php
Jetty Powered:http://www.eclipse.org/jetty/powered/
Contact the core Jetty developers at www.webtide.com
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 18 Next »

Session Clustering with Terracotta

Jetty has been integrated with Terracotta, providing a great clustering solution.
Since Jetty 6.1.12, the Jetty-Terracotta integration has been rewritten to provide better performance.
The Jetty-Terracotta integration is not bundled by default; it must be built from sources following the instructions below.

Requirements

  1. You need J2SE 1.5 or greater to build and run the Jetty-Terracotta integration.
  2. You need Jetty 6.1.12 or greater.
  3. You need to install Terracotta, we have tested Terracotta 2.6.4 or greater. We will refer to the installation directory as $TC_HOME.
  4. You need to download the Jetty TIM (Terracotta Integration Module), version 1.0.0 or 1.0.1, but not greater, no matter the Terracotta release you are using, from here.
    We are working on a updated version of the Jetty TIM and update the instructions when the new version of the Jetty TIM is compatible with the current Jetty-Terracotta integration.
    Unzip the Jetty TIM and copy tim-jetty-6.1-1.0.1.jar to $TC_HOME/modules/.

Build instructions

  1. Download and unzip a source bundle of Jetty 6.1.12 or greater from here. We will refer to the installation directory as $JETTY_HOME.
  2. Build it:
  3. Copy the target/terracotta-sessions.jar you just built into $JETTY_HOME>/lib/ext:

Jetty Configuration Files

Configuring Jetty to use Terracotta consists of creating a single TerracottaSessionIdManager per Jetty instance to generate unique session ids, and then setting up a special TerracottaSessionManager per each webapp that you want to be clustered.

The TerracottaSessionIdManager

One TerracottaSessionIdManager is configured per Jetty instance to generate unique session ids. These are the relevant lines to add in a jetty.xml file:

The TerracottaSessionIdManager is stored as an attribute on the Server instance for later retrieval under the name tcIdManager.
The workerName is a unique name for the Jetty node. In the example above it is "node1" but you can use any naming scheme you'd like. This is useful when hardware components such as load balancers can "stick" the requests to the same node to improve performances by limiting the session migrations among nodes.

The TerracottaSessionManager

Each web application whose sessions you want to cluster must use a TerracottaSessionManager instead of the default HashSessionManager.
The easiest way to do this is to create individual context deployer config files for each web application, and include these lines:

These lines ensure that a TerracottaSessionManager is established for each web application, and has access to the Jetty instance's unique TerracottaSessionIdManager we configured above.

Terracotta Configuration File

You need one Terracotta configuration file for each Jetty instance.
In the Terracotta configuration file part of the configuration is needed to setup correctly the Jetty-Terracotta integration, and the rest of the configuration is needed to setup the Terracotta server and the web applications.

The base Terracotta Configuration File

The base Terracotta configuration file that sets up the Jetty-Terracotta integration is the following:

You can create a Terracotta configuration file wherever you prefer in the file system. The file will be referenced by path in a system property to be passed on the command line (see below).
Copy and paste the example file content above into, for example, $JETTY_HOME/tc-config.xml.

Modifications to the Terracotta Configuration File

There are few places that needs to be modified in order for the Terracotta configuration file to correctly cluster your web application.

  1. Modify the location of the Terracotta server.
    The server element has the host attribute that needs to be modified to point to the host name or host address of the Terracotta server. In most simple configurations this can be the local host, but in more advanced configurations the Terracotta server is deployed in a separate host.
  2. Instrumented classes includes
    If you web application puts in the HTTP session only instances of JDK available classes (such as java.lang.Integer or java.lang.String), then no further configuration is needed.
    In case your web application puts in the HTTP session instances of classes belonging to the web application (such as a domain com.acme.domain.User class), then you need to specify also those classes as instrumented (without removing the Jetty classes), for example:
    You can also specify class expressions to match multiple classes, as specified here.
  3. Web application contexts
    You need to specify the context path at which the web application is configured, by defining the web-application elements in the Terracotta configuration file:
    If you forget to specify the web application context in the Terracotta configuration file, the web application will not be clustered.
    Use the special value ROOT to specify the root context. Note that the contexts do not have a leading slash.
    This configuration is needed with the Jetty TIM version 1.0.0 or 1.0.1. When the updated Jetty TIM will be completed, this portion will be likely not needed anymore, since it is a duplication of the configuration already specified with the Jetty context files.

Starting Terracotta and Jetty

The final steps require to start the Terracotta server and the Jetty servers.

  1. Start the Terracotta server
  2. Start the Jetty instance
    The command line above assumes that the Terracotta configuration file has been saved to $JETTY_HOME/tc-config.xml, and that the modified jetty.xml is in its usual location under $JETTY_HOME/etc/.
    Repeat this step for all Jetty nodes.

OLD INSTRUCTIONS

Session Clustering with Terracotta

Build Instructions

  1. Before you start, make sure you have installed release terracotta 2.4 or greater. We'll refer to the installation directory as <TC-HOME>.
  2. If you haven't already got a boot jar for terracotta for your jvm version, then make one now. On linux this is:
  3. Download and unzip a src bundle (6.1.4 onwards) or check out trunk or any tag from jetty-6.1.4 onwards. Here's how to do the checkout:
    We'll refer to the installation directory as <JETTY-HOME>.
  4. Build it if it isn't already:
  5. Go to the <JETTY_HOME>/contrib/terracotta directory and build it:
  6. Copy the target/terracotta-sessions.jar you just built into <JETTY-HOME>/lib/ext:

Configuration

Configuring Jetty to use Terracotta consists of creating a single TerracottaSessionIdManager per jetty instance to generate unqiue session ids, and then setting up a special TerracottaSessionManager per webapp to be distributed.

We've provided sample config files to do both of these things, so if you don't want to read further, you can just use them. Here's how to start jetty with terracotta and deploy the sample webapps that come with the terracotta distribution:

  1. build, then copy the DepartmentTaskList.war, Cart.war and Townsend.war files from <TC-HOME>/samples/sessions to <JETTY-HOME>/webapps
  2. copy these jetty context deployer config files which match the sample webapps into <JETTY-HOME>/contexts from <JETTY-HOME>/contrib/terracotta/src/main/resources:
    • cart.xml
    • departmentTaskList.xml
    • townsend.xml
  3. skip down to the #Starting section to run jetty

Otherwise, let's continue with looking into the configuration files.

The TerracottaSessionIdManager

One TerracottaSessionIdManager is configured per jetty instance to generate unique session ids. These are the relevant lines from <JETTY-HOME>/contrib/terracotta/src/main/resources/jetty.xml:

The workerName is a unqiue name for the jetty instance. In the example it is "fred" but you can use any naming scheme you'd like. We set the tcIdMgr object as a Server attribute so that we can reference it in other config files.

The TerracottaSessionManager

Each webapp whose sessions we want clustered must use a TerracottaSessionManager instead of the default HashSessionManager.

The easiest way to do this is to create individual context deployer config files for each webapp, and include these lines:

These lines ensure that a TerracottaSessionManager is established for each webapp, and has access to the jetty instance's unique session id generator we configured above.

Starting

  1. Start a terracotta server with a jetty configuration file. On linux this is:
  2. Set up the webapps that you want to use terracotta by following the instructions in the #Configuration section above.
  3. Run the <TC_HOME>/bin/dso-env.sh command to determine the appropriate JVM arguments to start jetty with.
    (The dso-env script will also create a Terracotta boot jar for you if you haven't already created one for your platform as described earlier.)
  4. Copy the output of the dso-env script and use it to start jetty:

You'll now have a jetty instance that is talking to terracotta to distribute sessions from your webapps. Rinse and repeat to create other jetty instances in the cluser. Don't forget to select a unique workerName for the other TerracottaSessionIdManagers. Also, if you just want to play around and run 2 jetty instances on the same machine, don't forget that you'll need to use port numbers for each!

A simple way to test if Terracotta session clustering is working is to restart the jetty server and verify that your session data is intact. You can also use the Terracotta console (<TC_HOME>/bin/admin.sh) to inspect the live session data.

  • No labels
Contact the core Jetty developers at www.webtide.com
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery