Web Sessions Installation Guide

Step 1: Requirements

• JDK 1.6 or higher.
• An application server.
• All clustered objects must be serializable.
• Download and unpack the BigMemory Max kit, which includes Terracotta Web Sessions.

Step 2: Install the Terracotta Sessions JAR

To cluster your application's web sessions, add the following two JAR files to your application's classpath, and place these files in the WEB-INF/lib folder of the Web Application Archive (WAR) on all of your application servers. These files are under ${TERRACOTTA_HOME}/.

• sessions/lib/web-sessions-<version>.jar

  <version> is the current version of the Terracotta Web Sessions JAR.

• apis/toolkit/lib/terracotta-toolkit-runtime-ee-<version>.jar

  The Terracotta Toolkit JAR contains the Terracotta client libraries. <version> is the current version of the Terracotta Toolkit JAR.

Step 3: Configure Web-Session Clustering

Terracotta servers, and Terracotta clients running on the application servers in the cluster, are configured with a Terracotta configuration file, tc-config.xml by default. Servers that are not started with a specified configuration will use a default configuration.

To add Terracotta clustering to your application, you must specify how Terracotta clients get their configuration by including the source in your web.xml file. Add the following configuration snippet to web.xml:

<filter>
 <filter-name>terracotta</filter-name>
 <!-- The filter class is specific to the application server. -->
 <filter-class>org.terracotta.session.{container-specific-class}</filter-class>
 <init-param>
   <param-name>tcConfigUrl</param-name>
   <!-- <init-param> of type tcConfigUrl has a <param-value> element containing 
        the URL or filepath (for example, /lib/tc-config.xml) to tc-config.xml. 
    If the Terracotta configuration source changes at a later time, 
    it must be updated in configuration. -->
   <param-value>localhost:9510</param-value>
 </init-param>
<!-- The following init-params are optional. 
 <init-param>
   <param-name>synchronousWrite</param-name>
   <param-value>false</param-value>
 </init-param>
 <init-param>
   <param-name>sessionLocking</param-name>
   <param-value>false</param-value>
 </init-param>
 <init-param>
   <param-name>maxBytesOnHeap</param-name>
   <param-value>128M</param-value>
 </init-param>
 <init-param>
   <param-name>maxBytesOffHeap</param-name>
   <param-value>4G</param-value>
 </init-param>
 <init-param>
   <param-name>rejoin</param-name>
   <param-value>false</param-value>
 </init-param>
 <init-param>
   <param-name>nonStopTimeout</param-name>
   <param-value>-1</param-value>
 </init-param>
 <init-param>
   <param-name>concurrency</param-name>
   <param-value>0</param-value>
 </init-param>
<!-- End of optional init-params. -->
</filter>
<filter-mapping>
 <!-- Must match filter name from above. -->
 <filter-name>terracotta</filter-name>
 <url-pattern>/*</url-pattern>
 <!-- Enable all available dispatchers. -->
 <dispatcher>ERROR</dispatcher>
 <dispatcher>INCLUDE</dispatcher>
 <dispatcher>FORWARD</dispatcher>
 <dispatcher>REQUEST</dispatcher>
</filter-mapping>

<filter-name> can contain a string of your choice. However, the value of <filter>/<filter-name> must match <filter-mapping>/<filter-name>.

Choose the appropriate value for <filter-class> from the following table.

Ensure that the Terracotta filter is the first <filter> element listed in web.xml. Filters processed ahead of the Terracotta filter may disrupt its processing.

web.xml should be in /WEB-INF if you are using a WAR file.

For more information about the optional init-params, refer to the Web Sessions Reference Guide.

Step 4: Start the Cluster

For Terracotta to function properly, make sure that your JAVA_HOME setting is set.

1. Start the Terracotta server:

   UNIX/Linux

   [PROMPT] ${TERRACOTTA_HOME}/server/bin/start-tc-server.sh
   

   Microsoft Windows

   [PROMPT] ${TERRACOTTA_HOME}\server\bin\start-tc-server.bat
   

2. Start your application servers.
3. (Optional) Start your management console (any JMX monitoring tool is fine) and connect it to your application server. For more information, refer to Monitoring and Management.

Step 5: Configure Terracotta Clustering

This step shows you how to run clients and servers on separate machines and add failover (High Availability). You will expand the Terracotta cluster and add High Availability by doing the following:

• Moving the Terracotta server to its own machine
• Creating a cluster with multiple Terracotta servers
• Creating multiple application nodes

These tasks bring your cluster closer to a production architecture.

Procedure:

1. Shut down the Terracotta cluster.

2. Create a Terracotta configuration file called tc-config.xml with contents similar to the following:

   <?xml version="1.0" encoding="UTF-8"?>
   <!-- All content copyright Terracotta, Inc., unless otherwise indicated.
    All rights reserved. -->
   <tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-9.xsd"
   xmlns:tc="http://www.terracotta.org/config"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   
    <servers>
      <!-- Sets where the Terracotta server can be found. 
       Replace the value of host with the server's IP address. -->
      <server host="server.1.ip.address" name="Server1">
        <data>%(user.home)/terracotta/server-data</data>
        <logs>%(user.home)/terracotta/server-logs</logs>
      </server>
      <!-- If using a standby Terracotta server, also referred to as 
       an ACTIVE-PASSIVE configuration, add the second server here. -->
      <server host="server.2.ip.address" name="Server2">
        <data>%(user.home)/terracotta/server-data</data>
        <logs>%(user.home)/terracotta/server-logs</logs>
      </server>
    </servers>
    <!-- Sets where the generated client logs are saved on clients. -->
    <clients>
      <logs>%(user.home)/terracotta/client-logs</logs>
    </clients>
   </tc:tc-config>
   

3. Install Terracotta on a separate machine for each server you configure in tc-config.xml.
4. Copy the tc-config.xml to a location accessible to the Terracotta servers.
5. Perform Step 2: Install the Terracotta Sessions JAR on each application node you want to run in the cluster. Be sure to install your application and any application servers on each node.

6. Edit web.xml on each application server to list both Terracotta servers:

   <param-value>server.1.ip.address:9510,server.2.ip.address:9510</param-value>
   

7. Start the Terracotta server in the following way, replacing "Server1" with the name you gave your server in tc-config.xml:

   UNIX/Linux

   [PROMPT] ${TERRACOTTA_HOME}/server/bin/start-tc-server.sh -f <path/to/tc-config.xml> \
      -n Server1 
   

   Microsoft Windows

   [PROMPT] ${TERRACOTTA_HOME}\server\bin\start-tc-server.bat -f <path\to\tc-config.xml> ^
      -n Server1 
   

   If you configured a second server, start that server in the same way on its machine, entering its name after the -n flag. The second server to start up becomes the hot standby, or PASSIVE. Any other servers you configured will also start up as standby servers.

8. Start all application servers.
9. Start your JMX console tool and view the cluster.

Step 6: Learn More

To learn more about working with a Terracotta cluster, see the following documents:

• Working with Terracotta Configuration Files – Explains how tc-config.xml is propagated and loaded in a Terracotta cluster in different environments.
• Terracotta Server Arrays – Shows how to design Terracotta clusters that are fault-tolerant, maintain data safety, and provide uninterrupted uptime.
• Configuring Terracotta Clusters For High Availability – Defines High Availability configuration properties and explains how to apply them.