Terracotta 3.3.0 - 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=3.3.0&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=3.3.0&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=3.3.0&pageID=AboutConfigurationFiles 
for more information on how Terracotta configuration is propagated.

Using a License Key
-------------------
If you received a file called product.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 product-key file should not be changed.
* Each Terracotta client and server instance in your cluster requires a copy of 
  the product-key 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 product
  key.
* Trial product keys expire after a trial period. See the file product.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 product.key.

   1. If product.key is in the Terracotta installation directory:

      -Dtc.install-root=/path/to/terracotta/installation

   2. If product.key is in a different location:

      -Dcom.tc.productkey.path=/path/to/product.key

   3. If you are using a Terracotta configuration file (tc-config.xml by 
      default), product.key can be specified in that file by adding the 
      following to the beginning of the configuration:

      <tc-properties>
           <property name="productkey.path" value="/path/to/product.key" />
      </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=3.3.0&pageID=Documentation).


----
All content copyright Terracotta, Inc., unless otherwise indicated. All rights reserved. 
http://www.terracotta.org

