Configuring the Terracotta Server
Overview
For your application end-points to be useful they must be able to utilize storage resources configured in your Terracotta Servers. The services offered make use of your server's underlying JVM and OS resources, including direct-memory (offheap) and disk persistence.
These server resources are configured in the
plugins section of the
Terracotta configuration file. For related information, see the section
The
Terracotta
Configuration File.
A Note on System Requirements and Considerations
We recommend to familiarize yourself with the following recommendations concerning the Terracotta Server:
Offheap Resources
The use of JVM Direct-Memory (offheap) is a central part of the operation of a Terracotta Server. In effect, you must allocate and make available to your server enough offheap memory for the proper operation of your application.
In your configuration file you define one ore more named offheap resources of a fixed size. These named resources are then referred to in the configuration of your application end-points to allow for their usage.
Refer to the section
Clustered Caches in the
Ehcache API Developer Guide for more details about the use of offheap resources.
Example Offheap Resource Configuration
1 | The plugins element is a direct child of the tc-config element |
2 | Defines primary-server-resource with size 384MB |
3 | Defines secondary-server-resource with size 256MB |
Data Directories
A data directory is a location on disk, identified by a name, and mapped to a disk location, where a Terracotta Server's data resides.
Data directories are commonly configured by server administrators and specified in the Terracotta Server configuration. Data directory names can be used by products that need durable storage for persistence and fast restart from crashes. For example, restartable cache managers need to be supplied with a data directory name to persist the restartable CacheManager specific data.
For information on restartable servers, see the section
Platform Persistence below. See also the sections
Fast Restartability and
Creating a Restartable Cache Manager in the
Ehcache API Developer Guide.
Sample Data Directories Configuration
<config xmlns:data="http://www.terracottatech.com/config/data-roots">
<data:data-directories>
<data:directory name="someData"> <!-- 1 -->
/mnt1/data <!-- 2 -->
</data:directory>
<data:directory name="otherData"> <!-- 3 -->
%(logs.path)/data <!-- 4 -->
</data:directory>
</data:data-directories>
</config>
1 | someData is a data directory name, |
2 | /mnt1/data is the disk location to which someData is mapped to. |
3 | otherData is another data directory name mapped to a different disk location, |
4 | %(logs.path)/data is the data directory which otherData is mapped to. Note the use of %(logs.path), which gets substituted with the logs path property |
See the description of parameter substitution in the section
The Terracotta Configuration File to check the complete list of available parameter substitutions.
General Notes on Configuring Data Directories
A data directory specified in a stripe configuration file must be specified in all the configurations of all stripes of the cluster.
Each data directory must be given a unique mount point (or disk location).
The data directories are created if they do not exist already.
Changing the disk location of the data directory between server restarts, without copying the data, is equivalent to erasing that data. It will cause unpredictable runtime errors that depend on the exact data lost.
Platform Persistence
The Terracotta server saves its internal state on a disk which enables server restarts without losing data. Platform persistence leverages data directories to store required data, so at least one data directory must be configured in the server configuration.
Note: Platform persistence is mandatory and a Terracotta server will refuse to start if there are no data directories defined.
Care must be taken to avoid losing data when restarting the stripe. Refer to the section
Restarting a Stripe for more details. Passive restartable servers automatically back up their data at restart for safety reasons. Refer to the topic
Passive servers in the section
Active and Passive Servers for more details.
Warning: Changing the disk location of the data directory used for platform persistence before restarting a server and not copying the data will result in the server starting as if it was a new server without any data.
Platform Persistence Configuration
By default, if a single data directory is defined, it will be used for platform persistence. If more than one data directory is defined, one of them must have the use-for-platform attribute set to true.
If the server cannot resolve a data directory to be used for platform persistence, it will fail to start.
Sample Server Configuration with Platform Persistence
1 | Indicates that the platform data directory is to be used for platform persistence |
Relation to Fast Restartability
The Ehcache Fast Restartability feature depends on, and makes use of, platform persistence.
Refer to the section
Fast Restartability in the
Ehcache API Developer Guide for more information.