|
Release: 2.6.2 Previous Releases
Publish Date: July, 2008 |
rate-15794179-85905
| Article Rating? |
|
|
|
About Terracotta Configuration Files |
|
Introduction
Terracotta XML configuration files define the characteristics and behavior of Terracotta servers and clients. The easiest way to create your own Terracotta configuration file is by editing a copy of one of the sample configuration files available in the /config-examples directory, located in the Terracotta home directory.
Where you locate the Terracotta configuration file, or how your Terracotta server and client configurations are loaded, depends on the stage your project is at and on its architecture. This document covers the following cases:
- Development stage, 1 Terracotta server
- Development stage, 2 Terracotta servers
- Deployment stage
For more information on configuration, including definitions of configuration elements, see docdraft:More Information.
How Terracotta Servers Get Configured
At startup, Terracotta servers should fetch their configuration from one of the following sources:
- A default configuration included with the Terracotta kit
- A local or remote XML file
These sources are explored below.
Default Configuration
If no configuration file is specified and no tc-config.xml exists in the directory in which the Terracotta instance is started, then default configuration values are used.
Local XML File (Default)
The file tc-config.xml is used by default if it is located in the directory in which a Terracotta instance is started and no configuration file is explicitly specified.
Local or Remote Configuration File
You can explicitly specify a configuration file by passing the -f option to the script used to start a Terracotta server. For example, to start a Terracotta server on UNIX/Linux using the provided script, enter:
where <path_to_configuration_file> can be a URL or a relative directory path.
How Terracotta Clients Get Configured
At startup, Terracotta clients should fetch their configuration from one of the following sources:
- A local or remote XML file
- A Terracotta server
These sources are explored below.
Local XML File (Default)
See the discussion for local XML file (default) in docdraft:How Terracotta Servers Get Configured.
Local or Remote Configuration File
To specify a configuration file for a Terracotta client, see docdraft:Clients in Development.
Terracotta Server
Terracotta clients can load configuration from a running Terracotta server by specifying its hostname and DSO port (see docdraft:Clients in Production).
Configuration in a Development Environment
In a development environment, using a different configuration file for each Terracotta client facilitates the testing and tuning of configuration options. This is an efficient and effective way to gain valuable insight on best practices for clustering your application with Terracotta DSO.
One-Server Setup in Development
For one Terracotta server, the default configuration is adequate.
To use the default configuration settings, simply start your Terracotta server using the start-tc-server.sh or start-tc-server.bat script in a directory that does not contain the file tc-config.xml:
If you want to specify a configuration file, use one of the approaches discussed in docdraft:How Terracotta Servers Get Configured.
Active-Passive Setup in Development
An active-passive setup uses at least two servers that should load the same configuration file.
The configuration file loaded by the Terracotta servers must define each server separately using <server> elements. For example:
...
<server host="%i" name="Server1">
...
<server host="%i" name="Server2">
...
By using the same configuration, Server2 can maintain the environment in the case of failover. Using the same configuration file simplifies maintenance and coordination between the Terracotta servers.
 |
Some elements in the <server> section, such as <server-logs>, must have different values for each server. |
With multiple <server> elements, the name attribute is required to avoid ambiguity when starting a server:
Clients in Development
You can explicitly specify a client's Terracotta configuration file by passing -Dtc.config when you start the client using the dso-java.sh script (or dso-java.bat for Windows):
where myApp.class.Main is the class used to launch the application you want to cluster with Terracotta.
|
On startup, Terracotta clients must fetch certain configuration properties from a Terracotta server. A client loading its own configuration will attempt to connect to the Terracotta servers named in that configuration. If none of the servers named in that configuration are available, the client cannot complete its startup. |
If tc-config.xml exists in the directory in which you run dso-java, it can be loaded without -Dtc.config:
Configuration in a Production Environment
For an efficient production environment, it's recommended that you maintain one configuration file. That file can be loaded by the Terracotta server (or servers) and pushed out to clients. While this is an optional approach, it's an effective way to centralize and decrease maintenance.
Clients in Production
For clients in production, you can set up the Terracotta environment before launching your application, or you can use the dso-java script.
Setting Up the Terracotta Environment
To start your application with the Terracotta client using your own scripts, first set the following environment variables:
- TC_INSTALL_DIR=<path_to_local_Terracotta_home>
- TC_CONFIG_PATH=<path/to/tc-config.xml>
or
- TC_CONFIG_PATH=<server_host>:<dso-port>
where <server_host>:<dso-port> points to the running Terracotta Server. The specified Terracotta server will push its configuration to the client Terracotta client.
If more than one Terracotta server is available, enter them in a comma-separated list:
If <server_host1> is unavailable, <server_host2> is used.
To complete setting up the Terracotta client's environment, run the following in UNIX/Linux:
In Windows, run the following:
Before starting up your application, confirm that the value of JAVA_OPTS is correct.
Using dso-java
You can explicitly specify a running Terracotta server as the source for configuration by passing -Dtc.config when you start the client using the dso-java.sh script (or dso-java.bat for Windows):
where myApp.class.Main is the class used to launch the application you want to cluster with Terracotta and <server_host>:<dso-port> points to the running Terracotta server. The specified Terracotta server will push its configuration to the Terracotta client.
If more than one Terracotta server is available, enter them in a comma-separated list:
If <server_host1> is unavailable, <server_host2> is used.
terracotta.xml
The file terracotta.xml, which contains a fragment of Terracotta configuration, can be part of a Terracotta integration module (TIM). When the TIM is loaded at runtime, terracotta.xml is inserted into the client configuration. For more information on TIMs and terracotta.xml, see the TIM manual.
|
If the use of terracotta.xml introduces duplicate elements into the client configuration, the value of the last element parsed is used. The last element parsed appears last in order in the configuration file. |
Which Configuration?
Each server and client must maintain separate log directories. By default, server logs are written to %(user.home)/terracotta/server-logs and client logs to %(user.home)/terracotta/client-logs.
To find out which configuration a server or client is using, search its logs for an INFO message containing the text "Configuration loaded from".
More Information
