Terracotta - Simple Scale for Enterprise Java =================================================== These simplified installation instructions are intended for quick

platform deployments such as those performed by operations staff. For more information on installing and configuring Terracotta for specific use cases, see http://www.terracotta.org/kit/reflector?kitID=default&pageID=Documentation Preparing to Run a Terracotta Cluster ------------------------------------This document is part of the Terracotta download for supported UNIX/Linux platforms and Microsoft Windows. For the latest supported platforms, including JVMs and application servers, see the list of certified Terracotta platforms at http://www.terracotta.org/kit/reflector?kitID=default&pageID=PlatformSupport General Considerations ---------------------The following is a checklist of general preparedness issues: * * * * Operating systems are up to date, including patches. Java (JDK) is installed on all nodes. JAVA_HOME is set correctly for the user under which Terracotta will run. The network path between Terracotta server machines in the cluster is clean. A clean path has low latency (end-to-end Gigabit connections are recommended), and no packet loss. NOTE: In a production environment, it is likely that the Terracotta cluster will consist of at least one active server and one backup (or "hot standby") server. * The network path between Terracotta server machines and Terracotta client machines is clean. Terracotta clients are the application servers in a cluster. A clean path has low latency (end-to-end Gigabit connections are recommended), and no packet loss. * None of the network paths between cluster nodes are blocked by a firewall. * If Terracotta servers are configured to generate logs, be sure there is enough space where the logs are stored. You can set the path for log files in the Terracotta configuration file (tc-config.xml by default) using the <logs> element found in the <clients> section and in each <server> section. Configuring Terracotta ---------------------Terracotta is configured using a configuration file (tc-config.xml by default). The major sections include <servers> (setting up Terracotta servers), <clients> (setting Terracotta clients or application servers), and <application> (the application being clustered). If no configuration file is provided, a default configuration is used. Servers can be configured with a name, bind (IP) address, and various ports. Naming a server is recommended because it allows you to use that name when executing commands and scripts that must refer to the server. See tc-config-reference.xml in the Terracotta docs directory for an annotated version of the Terracotta configuration file.

Terracotta servers and clients can obtain configuration in different ways. One way is to start the server with the following flag: -Dtc.config=<path/to/Terracotta/configuration/file> Then start all clients with the following flag: -Dtc.config=<server IP or host address>:<port number> Clients started this way obtain their configuration from the specified server (see Starting Terracotta, below). See http://www.terracotta.org/kit/reflector?kitID=default&pageID=AboutConfigurat ionFiles for more information on how Terracotta configuration is propagated. Using a License Key ------------------If you received a file called terracotta-license.key from Terracotta, save it to your Terracotta installation's root directory and start or restart Terracotta. (For express installations, see below). This file contains the license key, or product key, that must be loaded to activate your non-OSS version of Terracotta. Note the following: * The name of the terracotta-license file should not be changed. * Each Terracotta client and server instance in your cluster requires a copy of the license file. * The number of Terracotta clients that can run simultaneously in the cluster is fixed by the product key and cannot be changed without obtaining a new terraco tta-license key. * Trial product keys expire after a trial period. See the file terracotta-licens e.key for the limitations on the key you have. Expiration warnings are issued both to logs and standard output to allow enough time to contact Terracotta for an extension. * EXPRESS INSTALLATIONS: If you are using an express installation, such as for distributed Ehcache, you must set one of the following properties for your application, depending on the location of terracotta-license.key. 1. If terracotta-license.key is in the Terracotta installation directory: -Dtc.install-root=/path/to/terracotta/installation 2. If terracotta-license.key is in a different location: -Dcom.tc.productkey.path=/path/to/terracotta-license.key 3. If you are using a Terracotta configuration file (tc-config.xml by default), terracotta-license.key can be specified in that file by adding t he following to the beginning of the configuration: <tc-properties> <property name="productkey.path" value="/path/to/" /> </tc-properties>

Starting Terracotta ------------------The startup script for Terracotta servers is start-tc-server.sh (UNIX/Linux) or start-tc-server.bat (Microsoft Windows). If you have configured more than one Terracotta server, start a specific server by referring to its name with the -n flag. For example, to start a server you named "myServer" from the Terracotta home directory and using a specific configuration file, enter the following: start-tc-server.sh -n myServer -f <path/to/Terracotta/configuration/file> For Microsoft Windows, enter the following: start-tc-server.bat -n myServer -f <path\to\Terracotta\configuration\file> More Information ---------------You'll find a number of helpful guides in the documentation section (http://www.terracotta.org/kit/reflector?kitID=default&pageID=Documentation). ---All content copyright Terracotta, Inc., unless otherwise indicated. All rights r eserved. http://www.terracotta.org