Terracotta XML configuration files set the characteristics and behavior of Terracotta server instances and Terracotta clients. The easiest way to create your own Terracotta configuration file is by editing a copy of one of the sample configuration files available with the Terracotta kit.
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:
At startup, Terracotta servers load their configuration from one of the following sources:
These sources are explored below.
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.
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.
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:
start-tc-server.sh -f <path_to_configuration_file>
where <path_to_configuration_file> can be a URL or a relative directory path. In Microsoft Windows, use
start-tc-server.bat
.
At startup, Terracotta clients load their configuration from one of the following sources:
The first two sources are explored below.
See the discussion for local XML file (default) in How Terracotta Servers Get Configured.
To specify a configuration file for a Terracotta client, see Clients in Development.
Terracotta clients can load configuration from a running Terracotta server by specifying its hostname and DSO port (see Clients in Production).
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.
For one Terracotta server, the default configuration is adequate.
To use the default configuration settings, 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
:
[PROMPT] ${TERRACOTTA_HOME}\bin\start-tc-server.sh
To specify a configuration file, use one of the approaches discussed in How Terracotta Servers Get Configured.
An two-server setup, sometimes referred to as an active-passive setup, has one active server instance and one "hot standby" (the passive, or backup) 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:
<tc:tc-config xsi:schemaLocation="http://www.terracotta.org/schema/terracotta-5.xsd"
xmlns:tc="http://www.terracotta.org/config"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
<!-- Use an IP address or a resolvable host name for the host attribute. -->
<server host="123.456.7.890" name="Server1">
...
<server host="myResolvableHostName" name="Server2">
...
</tc:tc-config>
Assuming Server1 is the active server, using the same configuration allows Server2 to be the hot standby and maintain the environment in case of failover.
You can explicitly specify a client's Terracotta configuration file by passing
-Dtc.config=path/to/my-tc-config.xml
when you start your application with the Terracotta client.
DSO users can use the
dso-java.sh
script (or
dso-java.bat
for Windows):
dso-java.sh -Dtc.config=path/to/my-tc-config.xml -cp classes myApp.class.Main
where
myApp.class.Main
is the class used to launch the application you want to cluster with Terracotta. In Microsoft Windows, use
dsa-java.bat
.
If
tc-config.xml
exists in the directory in which you run dso-java, it can be loaded without
-Dtc.config
.
|
If you do not require DSO, do not use the dso-java script. Terracotta products provide simple configuration setups.
If you are using DSO, you may want to avoid using the dso-java script and start your application with the Terracotta client using your own scripts. See Setting Up the Terracotta Environment.
|
For an efficient production environment, it's recommended that you maintain one Terracotta 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.
If your Terracotta configuration file uses "%i" for the hostname attribute in its server element, change it to the actual hostname in production. For example, if in development you used the following:
<server host="%i" name="Server1">
and the production host's hostname is myHostName, then change the host attribute to the myHostName:
<server host="myHostName" name="Server1">
For clients in production, you can set up the Terracotta environment before launching your application. DSO users can use the dso-java script.
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>
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 Terracotta client.
If more than one Terracotta server is available, enter them in a comma-separated list:
TC_CONFIG_PATH=<server_host1>:<dso-port>,<server_host2>:<dso-port>
If <server_host1> is unavailable, <server_host2> is used.
If using DSO, complete setting up the Terracotta client's environment by running the following:
Terracotta products without DSO (also called the "express" installation) can set a configuration path using their own configuration files.
For Terracotta Distributed Ehcache and Distributed Ehcache for Hibernate, use the <terracottaConfig> element in the Ehcache configuration file (
ehcache.xml
by default):
<terracottaConfig url="localhost:9510" />
For Quartz, use the
org.quartz.jobStore.tcConfigUrl
property in the Quartz properties file (
quartz.properties
by default):
org.quartz.jobStore.tcConfigUrl = /myPath/to/tc-config.xml
For Terracotta Web Sessions, use the appropriate elements in
web.xml
or
context.xml
(see Web Sessions Express Installation).
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
Terracotta Integration Modules Manual
.
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".
