Jetty Web Server Quick Start |
rate-10223806-92789
| Article Rating? |
|
|
|
Table of Contents
Introduction
This guide is intended to step you through the process of installing and deploying your web application in a Terracotta Sessions cluster with the Jetty web server. After completing these tasks, you should have a fully-functioning development environment.
The following diagram shows the architecture of a typical Terracotta-enabled web application:
The load balancer parcels out HTTP requests from the Internet to each application server. To maximize the locality of reference of the clustered HTTP session data, the load balancer uses HTTP session affinity so all requests corresponding to the same HTTP session are routed to the same application server. However, with a Terracotta-enabled web application, any application server can process any request.
The application servers run both your web application and the Terracotta client software. While more application servers may be deployed as needed to handle additional request load, for simplicity this guide will assume there are three active application servers.
The Terracotta server acts as the data store for HTTP session data and coordinates access by the application servers to that session data.
To achieve high availability (HA), your system architecture could be similar to the following:
For more information on setting up an HA cluster, see Creating a Terracotta Server Cluster and Network Active-Passive Deployment Guide.
Overview
To get your system installed, configured, and running, follow these steps:
- Download Terracotta, Java, and the application server.
- Install the software on the cluster.
- Start the Terracotta server.
- Configure the Terracotta clients and the application servers.
- Start the application server instances.
- Test and troubleshoot.
These steps are illustrated in the flowchart below (click it to see a larger image). This document covers in detail the portion enclosed by a broken-line border. The steps outside the broken-line border are covered in Configuring Terracotta DSO for Your Application.
Download
Install
- Install Java on all machines
See the Platform Support document for the latest information on required versions and dependencies.
- Install Terracotta software on all machines
Terracotta software is installed in the same way on the server machine and on the application servers (clients). In this guide the local Terracotta installation directory is referred to as <Terracotta_installation_directory> or <path_to_local_Terracotta_home>.
- The TIM for Jetty on all of the application machines
- Jetty web server on all of the application server machines
- Install the web application on all of the application server machines
Start the Terracotta Server
In a development environment, you can start the Terracotta software on the server machine without providing a configuration file. The Terracotta server will run with a default configuration.
To start the Terracotta server, execute the start-tc-server.sh script found in the <Terracotta_installation_directory>/bin directory or the start-tc-server.bat script found in the <Terracotta_installation_directory>\bin directory. You should see output similar to the following:
See the Tools Guide for more information on the start-tc-server script.
Configure the Terracotta Clients
After you install the Terracotta software on each application server, copy (or unpack) the TIM to <Terracotta_installation_directory>/modules, the default location for TIMs. You can also create a separate directory for the TIM (UNIX/Linux):
mkdir -p <Terracotta_installation_directory>/modules/tim-jetty-<jetty_version>/<tim_version>/org/mortbay/jetty
For Windows, use the equivalent commands to create the directory. For more information on TIMs, including how to create TIM repositories, see the Terracotta Configuration Guide and Reference
.
Create a Terracotta configuration file, tc-config.xml, on each application-server installation. Be sure to add a <clients/> section as shown.
<tc:tc-config xmlns:tc="http://www.terracotta.org/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-4.xsd">
<servers>
<!-- The <update-check> element helps ensure that you're using the latest version of Terracotta DSO.
Out-of-date versions trigger a message to log and standard output. -->
<update-check>
<enabled>true</enabled>
</update-check>
<server host="my.tc.server">
<dso-port>9510</dso-port>
</server>
</servers>
<!-- The <clients/> section contains Terracotta integration module (TIM) file information.
The <module/> element shown is for a TIM file named tim-jetty-6.1.4-1.1.0-SNAPSHOT.jar. -->
<clients>
<modules>
<module name="tim-jetty-6.1.4" version="1.1.0-SNAPSHOT" />
</modules>
</clients>
<application>
<dso>
<web-applications>
<web-application>your_web_app1</web-application>
<web-application>your_web_app2</web-application>
</web-applications>
</dso>
</application>
</tc:tc-config>
 |
If the TIM is not in <Terracotta_installation_directory>/modules, add a group-id attribute to the <module/> element. |
Each Terracotta client will load — and be configured by — a local copy of this example tc-config.xml.
The relevant elements in the example above are discussed in the following sections. For a comprehensive guide to the contents of tc-config.xml, see the file tc-config-reference.xml in the Terracotta <Terracotta_installation_directory>/docs directory.
<server> Element
The <server> element declares the Terracotta server. A Terracotta client loads the configuration in its tc-config.xml and finds the Terracotta server using the <server> "host" attribute value, and the port specified in <dso-port>. "host" can show the Terracotta server machine's IP address or domain-name address.
In the example above, <dso-port> could be omitted because 9510 is the default port Terracotta uses. However, if you want Terracotta DSO to use a different port, change the value of <dso-port>.
<web-application> Element
The value of the <web-application> element must equal the value of your web application's context root. There are a number of ways to define the context root in a Jetty web server's configuration (in order of precedence):
- the <context-root> element in the application.xml file if your web application is deployed using an EAR file;
- the context root defined as <Set name="contextPath">context_root</Set> under the <Configure> element in jetty.xml or jetty-web.xml;
- the base name of the web application's .war file if you do not have a context root defined.
For more information on configuring the Jetty web server, see the Jetty documentation.
|
To set the value of the <web-application> element in tc-config.xml to the default web-application context, use the special value "ROOT" (without quotation marks). |
Use one <web-application> element for each web application you want to cluster.
Session Continuity Across Servers
In a multi-server environment, session continuity allows a session to be recognized and proceed unaffected regardless of which application server receives its requests. If your setup includes two or more application servers, a way of maintaining session continuity must be implemented. In production environments, this is often achieved through the use of a load balancer.
 |
If you are using IP addresses to connect to your application servers, use a load balancer to maintain session continuity. |
If you are testing without a load balancer, session continuity can be maintained by configuring the cookie domain to include your application servers. Set the Terracotta property session.cookie.domain on each Terracotta client by passing the following system property at startup:
where .example.com is your domain. Be sure to include the leading period (".") in your domain specification.
You can also configure this property in the client's local tc.properties file:
|
Remember that Terracotta clients run with your application servers and should not be confused with the Terracotta server. |
With this setting, requests (with the same session ID) directed at the example.com domain can maintain a session across servers. If your application servers are named Server1 and Server2, a request to server1.example.com and a request with the same session ID to server2.example.com are recognized as belonging to the same session.
Some application servers allow you to set the cookie domain, and that value may override the one in the Terracotta client. If you set the cookie domain in your application server, it's recommended that you clear the Terracotta cookie-domain setting to avoid potential conflicts.
Configure the Jetty Web Server
Configure the Jetty web server to run with the Terracotta software by adding the following to the beginning of the script you use to start the Jetty web server:
TC_INSTALL_DIR=<path_to_local_Terracotta_home>
TC_CONFIG_PATH=<path_to_local_tc-config.xml>
. $TC_INSTALL_DIR/bin/dso-env.sh -q
export JAVA_OPTS="$TC_JAVA_OPTS $JAVA_OPTS"
set TC_INSTALL_DIR=<path_to_local_terracotta_home>
set TC_CONFIG_PATH=<path_to_local_tc-config.xml>
%TC_INSTALL_DIR%\bin\dso-env.bat -q
set JAVA_OPTS=%TC_JAVA_OPTS%;%JAVA_OPTS%
Example
Copy the appropriate snippet shown above into a script called set-tc-env.sh or set-tc-env.bat.
For UNIX/Linux, if you installed the Terracotta kit version 2.6.1 in usr/local/terracotta-2.6.1, use the following values:
For Windows, if you installed the Terracotta kit version 2.6.1 in Program Files\terracotta-261, use the following values:use:
For this example, tc-config.xml is assumed to be saved in the root of the Terracotta installation path. The value of TC_CONFIG_PATH implies that we have placed tc-config.xml in usr/local/terracotta-2.6.1 or Program Files\terracotta-261.
For UNIX/Linux, run the script as shown:
For Windows, omit the leading period and space, and run set-tc-env.bat.
After the script exits, you can check the value of JAVA_OPTS (shown for Linux):
In Windows, %JAVA_OPTS% will have a similar value. Note that the JAR filename specified by -Xbootclasspath varies based on your installation environment.
Start the Jetty Web Server
Start the Jetty web server using the modified start script.
| Start the Jetty web server in the same way on all of the application server machines. |
A Single Startup Script
It is common to wrap this process in a single script. The following could function as a Jetty web-server start script:
TC_INSTALL_DIR=<path_to_local_Terracotta_home>
TC_CONFIG_PATH=<path/to/tc-config.xml
. ${TC_INSTALL_DIR}/bin/dso-env.sh -q
export JAVA_OPTS="$TC_JAVA_OPTS $JAVA_OPTS"
$JETTY_HOME/bin/jetty.sh
setlocal
set TC_INSTALL_DIR=<path_to_local_Terracotta_home>
set TC_CONFIG_PATH=<path\to\tc-config.xml>
call %TC_INSTALL_DIR%\bin\dso-env.bat -q
set JAVA_OPTS=%TC_JAVA_OPTS%
call %BEA_HOME%\bin\jetty.bat
endlocal
Test and Troubleshoot
After the Terracotta server, web application server, and application are up and running, you can begin to test and troubleshoot. Deciphering exceptions, functional testing, and load testing — all discussed below — are crucial to making your development environment succeed.
Exception Handling
During the initial stages of your development testing, the following exceptions are likely to be thrown:
- TCNonPortableObjectException (non-portable class exception)
- UnlockedSharedObjectException (unlocked shared object exception)
You can easily fix the conditions that cause these common exceptions using simple tuning techniques. See Configuring Terracotta DSO for Your Application for more information.
Testing With a Load Balancer
For testing purposes, the Terracotta installation includes a simple TCP proxy that can be used as a load balancer.
Functional testing with a load balancer when configuring a cluster of more than one physical machine ensures discovery of problems that could manifest as unexpected results in a production environment.
|
Do not use this TCP proxy in a production environment. Production environments require production-quality hardware or software load balancers. |
Without a load balancer, it's likely that each access — even for the same session — will occur within different cookie domains, with each server starting a new session without knowledge of previous session history. In this case, it may appear that clustering is not working.
If clustering is disabled and more than one application server instance is running on the same machine, unexpected results may occur. In this case, existing sessions may be lost because each instance runs in the same domain without access to the other instances' cookie (or session) sets. Browsers can have only one cookie from the same domain at a time.
For more information on the interaction of cookies and domains, see Sessions Quick Start.
TCP Proxy Start Script
The following is a script for starting the TCP proxy in a UNIX/Linux environment:
Here's a version of the script with example values:
To run the TCP proxy, execute the script on the load-balancer machine using bin/start-loadbalancer.sh and look for output similar to the following:
Load Testing
When performing load testing, be sure that every process has a dedicated machine. Each application server, the Terracotta server, and the software load balancer should run on a separate machine. This minimizes process resource contention and ensures that you are testing the cluster itself, not any particular OS process or thread scheduler.
Be sure to put load on all application servers in the cluster. Putting load on only one server is not a realistic test, and does not account for the overhead of synchronizing session states that may occur with other session replication technologies. With the Terracotta software, this load is minimized; however, with other solutions, such as peer-to-peer based replication, this load is non-trivial and is an important part of the overall performance picture.
