How Terracotta Servers Get Configured
To configure the Terracotta server, create a tc-config.xml configuration file, or update the one that is provided in the config-samples/ directory of the BigMemory Max kit. For example:
<?xml version="1.0" encoding="UTF-8" ?>
<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-9.xsd">
<servers>
<server host="localhost" name="My Server Name1">
<!-- Specify the path where the server should store its data. -->
<data>/local/disk/path/to/terracotta/server1-data</data>
<!-- Specify the port where the server should listen for client
traffic. -->
<tsa-port>9510</tsa-port>
<jmx-port>9520</jmx-port>
<tsa-group-port>9530</tsa-group-port>
<management-port>9540</management-port>
<!-- Enable BigMemory on the server. -->
<dataStorage size="800g">
<offheap size="200g"/>
<!-- Hybrid storage is optional. -->
<hybrid/>
</dataStorage>
</server>
<server host="localhost" name="My Server Name2">
<data>/local/disk/path/to/terracotta/server2-data</data>
<tsa-port>9510</tsa-port>
<jmx-port>9520</jmx-port>
<tsa-group-port>9530</tsa-group-port>
<management-port>9540</management-port>
<dataStorage size="200g">
<offheap size="200g"/>
</dataStorage>
</server>
<!-- Add the restartable element for Fast Restartability (optional). -->
<restartable enabled="true"/>
</servers>
<clients>
<logs>logs-%i</logs>
</clients>
</tc:tc-config>
To successfully configure a Terracotta Server Array using the Terracotta configuration file, note the following:
Two or more servers should be defined in the <servers> section of the Terracotta configuration file.
<tsa-port> is the port that the Terracotta server listens to for client traffic.
<jmx-port> is the port that the Terracotta server's JMX Connector listens to.
Note: Listening on the <jmx-port> is deprecated. Alternatively, use the monitoring features provided by the Terracotta Management Console (see the Terracotta Management Console User Guide) and the WAN Replication Service (see the WAN Replication User Guide).
<jmx-port> is disabled by default. If you want to enable it, add jmx-enabled="true" in the <server> elements. For example:
<server host="localhost" name="My Server Name1" jmx-enabled="true">
<tsa-group-port> is the port used by the Terracotta server to communicate with other Terracotta servers.
<management-port> is the port that the Terracotta Management Console (TMC) uses.
Under <servers>, use either <server> or <mirror-group> configurations, but not a mixture. You may configure multiple servers or multiple mirror groups. <server> instances under <servers> work together as a mirror group. To create more than one stripe, use <mirror-group> instances.
Terracotta server instances must not share data directories. Each server's <data> element should point to a different and preferably local data directory.
For data persistence, configure fast restartability. Enabling <restartable> means that the shared in-memory data is backed up and, in case of failure, it is automatically restored. Setting <restartable> to "false" or omitting the <restartable> element are two ways to configure no persistence.
Each server requires an off-heap store, which allows all data to be stored in-memory, limited only by the amount of memory in your server. The minimum <offheap> size is 4 GB. Additional hybrid storage is optional. Specify the <dataStorage> size and the <offheap> size. The <offheap> size can be set to the amount of memory available in your server for data. If you enable <hybrid>, then the <dataStorage> size can exceed the <offheap> size.
All servers and clients should be running the same version of Terracotta and Java.
Server Startup Behavior
At startup, Terracotta servers load 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:
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.
Note: Cygwin (on Windows) is not supported for this feature.