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.
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 config file you define one or 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.
Offheap Resource Configuration
Offheap resources can be configured with the offheap-resources property. By default, an offheap resource with name main and size 512MB is defined on the server.
The following snippet shows the configuration of two offheap resources - primary-server-resource with size 384MB, and secondary-server-resource with size 256MB.
offheap-resources=primary-server-resource:384MB,secondary-server-resource: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
Server Persistence below. See also the sections
Fast Restartability and
Creating a Restartable Cache Manager in the
Ehcache API Developer Guide.
Data Directories Configuration
Data directories can be configured with the data-dirs property. By default, a data directory with name main is defined which maps to disk location %(user.home)/terracotta/user-data/main.
The following snippet shows the configuration of two data directories - someData with disk location /mnt1/data, and otherData with location %(logs.path)/data.
data-dirs=someData:/mnt1/data,otherData:%(logs.path)/data
%(logs.path) gets substituted with the logs path system property. Visit the section
Parameter Substitution for the complete list of substitutable parameters.
General Notes on Configuring Data Directories
A data directory specified on a server must be specified on all the servers in 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.
Server Persistence
The Terracotta server saves its internal state on a disk which enables server restarts without loss of data.
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.
Server Persistence Configuration
Server persistence is configured with the metadata-dir property. By default, it is set to %(user.home)/terracotta/metadata.
The following snippet shows the configuration of metadata-dir to disk location /path/to/metadata-dir:
metadata-dir=/path/to/metadata-dir
Relation to Fast Restartability
The Ehcache Fast Restartability feature depends on, and makes use of, server persistence.
Refer to the section
Fast Restartability in the
Ehcache API Developer Guide for more information.