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.

We recommend to familiarize yourself with the following recommendations concerning the Terracotta Server:

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 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.

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 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.

%(logs.path) gets substituted with the logs path system property. Visit the section Parameter Substitution for the complete list of substitutable parameters.

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 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:

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.