The Terracotta Server provides powerful distributed in-memory data management capabilities for Terracotta products (such as Ehcache) and is the backbone for Terracotta clusters.

A Terracotta Server Array can vary from a basic two-node tandem to a multi-node array (Terracotta Server Array (TSA)) providing configurable scale, high performance, and deep failover coverage.

Add distributed caching capabilities to your Ehcache deployment today!

Terracotta additionally offers various other open source projects and code libraries which may be of interest.

Some key features of the Terracotta Server include:

Advanced features such as fast-restart persistence, advance management features and security are available in commercially supported versions from Software AG.

Getting Started

Getting started with the Terracotta Server 4.x is a simple matter of downloading, changing a few configuration items, and starting it up. Because the server isn't very interesting without something using it, this guide will show you how to put the Terracotta Server to its most common use: clustering an Ehcache cache.

Download and Install

Installing and using Terracotta Server is as easy as downloading the kit and ensuring that the correct files are on your application's classpath. The only platform requirement is using JDK 1.6 or higher.

1 - Download the Terracotta Server.

The kit is packaged as a tar.gz file. Download it then unpack it on the command line or with the appropriate decompression application.

2 - Update Classpath

Add the following JARs from within the kit to your application's classpath (if they are not already there):
  • apis/ehcache/lib/ehcache-<version>.jar – This file contains the Ehcache API.
  • apis/ehcache/lib/slf4j-api-<version>.jar – This file is the bridge, or logging facade, to the BigMemory Max logging framework.
  • apis/toolkit/lib/terracotta-toolkit-runtime-<version>.jar – This JAR contains the libraries that enable connecting Ehcache to the Terracotta Server.

3 - Configure Ehcache

Configure Ehcache to utilize the Terracotta Server. Create an `ehcache.xml` configuration file, or modify your own existing Ehcache configuration, or update the one that is provided in the config-samples/ directory of the downloaded Terracotta Server kit. For example: 
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd"
     name="myBigMemoryMaxConfig">

  <!-- Tell BigMemory where to write its data to disk. -->
  <diskStore path="/path/to/my/disk/store/directory"/>

  <!-- Set 'maxBytesLocalOffHeap' to the amount of off-heap in-memory 
  storage you want to use. This memory is invisible to the Java garbage 
  collector, providing for gigabytes to terabytes of in-memory data without 
  garbage collection pauses. --> 
  <cache name="myBigMemoryMaxStore"
        maxBytesLocalHeap="512M"
        maxBytesLocalOffHeap="8G">

    <!-- Tell BigMemory to use the "localRestartable" persistence
    strategy for fast restart (optional). -->
    <persistence strategy="localRestartable"/>

    <!-- Include the terracotta element so that the data set will be 
    managed as a client of the Terracotta server array.  -->
    <terracotta/>
  </cache>

  <!-- Specify where to find the server array configuration. In this 
  case, the configuration is retrieved from the local server. --> 
  <terracottaConfig url="localhost:9510" />

</ehcache>
Ensure that your `ehcache.xml` file is in the top-level of your classpath.

Note

1 - Use the -XX:MaxDirectMemorySize Java option to allocate enough direct memory in the JVM to accomodate the off-heap storage specified in your configuration, plus at least 250MB to allow for other direct memory usage that might occur in your application. For example: -XX:MaxDirectMemorySize=9G Set MaxDirectMemorySize to the amount of BigMemory you have.
2 - Also, allocate at least enough heap using the -Xmx Java option to accomodate the on-heap storage specified in your configuration, plus enough extra heap to run the rest of your application. For example: -Xmx1g
3 - If necessary, define the JAVA_HOME environment variable.

Start The Terracotta Server

You should be able to run the server for testing without a configuration change, but we will give you a pointer on where to find the configuration file before starting the server.

1 - Configure the Terracotta Server

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 terracotta 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 Name">
       <!-- Specify the port clients will connect to the server on. -->
       <tsa-port>9510</tsa-port>
       <!-- Configure memory (off-heap) space to use on the server. -->
       <dataStorage size=”4g”>
       </dataStorage>
    </server>
  </servers>
  <clients>
    <logs>logs-%i</logs>
  </clients>
</tc:tc-config>
Place your `tc-config.xml` file in the Terracotta `server/` directory.

2 - Start the Terracotta Server

In a terminal, change to your Terracotta `server/` directory. Then execute the start-tc-server command. For *nix systems: 
%> cd /path/to/terracotta-<version>/server
%> ./bin/start-tc-server.sh
For Windows systems: 
> cd \path\to\terracotta-<version>\server
> .\bin\start-tc-server.bat
You should see confirmation in the terminal that the server started.

Not quite ready yet?

Read the user documentation for everything you've been wondering about the new API!

Getting Started

Getting started with the Terracotta Server 5.x/10.x is a simple matter of downloading, changing a few configuration items, and starting it up. Because the server isn't very interesting without something using it, this guide will show you how to put the Terracotta Server to its most common use: clustering an Ehcache cache.

Download and Install

Installing and using Terracotta Server is as easy as downloading the kit and ensuring that the correct files are on your application's classpath. The only platform requirement is using JDK 1.8 or higher.

1 - Download the Terracotta Server.

The kit is packaged as a .tar.gz file. Download it then unpack it on the command line or with the appropriate decompression application.

2 - Update Classpath

Add the following JAR from within the kit to your application's classpath (if they are not already there): apis/ehcache-terracotta-client-all.jar – This file contains the Ehcache API.

3 - Configure Ehcache

3.1 - Through XML

Configure Ehcache to utilize the Terracotta Server. Create an ehcache.xml configuration file, or modify your own existing Ehcache configuration, or update the one that is provided in the config-samples/ directory of the downloaded Terracotta Server kit. For example:

  .....
  <cache alias="foo"> 
    <key-type>java.lang.String</key-type> 
    <resources>
      <heap unit="entries">2000</heap> 
      <offheap unit="MB">500</offheap> 
    </resources>
  </cache>

  <cache-template name="myDefaults"> 
    <key-type>java.lang.Long</key-type>
    <value-type>java.lang.String</value-type>
    <heap unit="entries">200</heap>
  </cache-template>

  <cache alias="bar" uses-template="myDefaults"> 
    <key-type>java.lang.Number</key-type>
  </cache>

  <cache alias="simpleCache" uses-template="myDefaults" />
  .....
Ensure that your ehcache.xml file is in the top-level of your classpath.

3.2 - Through Java

As with the previous versions of Ehcache, the canonical way of dealing with Cache is through a CacheManager: 

  .....
  CacheManager cacheManager = CacheManagerBuilder.newCacheManagerBuilder()
    .withCache("preConfigured", CacheConfigurationBuilder
      .newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10))) 
    .build(); 

  cacheManager.init(); 

  Cache<Long, String> preConfigured = cacheManager.getCache("preConfigured", Long.class, String.class); 

  Cache<Long, String> myCache = cacheManager.createCache("myCache", 
    CacheConfigurationBuilder.newCacheConfigurationBuilder(Long.class, String.class, ResourcePoolsBuilder.heap(10)).build());

  myCache.put(1L, "da one!"); 
  String value = myCache.get(1L); 

  cacheManager.removeCache("preConfigured"); 

  cacheManager.close();
  .....
Further, for creating the cache manager with clustering support, you will need to provide the clustering service configuration: 

  .....
  final CacheManagerBuilder<PersistentCacheManager> clusteredCacheManagerBuilder =
    CacheManagerBuilder.newCacheManagerBuilder() 
      .with(ClusteringServiceConfigurationBuilder
        .cluster(URI.create("terracotta://localhost:9510/my-application")).autoCreate()); 

  final PersistentCacheManager cacheManager = clusteredCacheManagerBuilder.build(true); 

  cacheManager.close();
  .....


Start The Terracotta Server

1 - Configure the Terracotta Server

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 terracotta kit. For example: 

  <?xml version="1.0" encoding="UTF-8"?>
  <tc-config xmlns="http://www.terracotta.org/config" xmlns:ohr="http://www.terracotta.org/config/offheap-resource">
    <services>
      <service id="resources">
        <ohr:offheap-resources>
          <ohr:resource name="primary-server-resource" unit="MB">128</ohr:resource>   
          <ohr:resource name="secondary-server-resource" unit="MB">96</ohr:resource>  
        </ohr:offheap-resources>
      </service>
    </services>
  </tc-config>
The above configuration defines two named server off-heap resources:
An off-heap resource of 128 MB size named primary-server-resource.
Another off-heap resource named secondary-server-resource with 96 MB capacity.

2 - Start the Terracotta Server

Assuming that you have the clustered EhCache kit available locally, start with extracting the ehcache-clustered kit. Change to your extracted directory and then execute the start-tc-server script as below to start the Terracotta server with the above configuration:

On Windows: 

  cd <path/to/terracotta/kit>/server/bin
  start-tc-server.bat -f <path/to/server/config>/tc-config.xml
On Unix/Mac: 

  cd <path/to/terracotta/kit>/server/bin
  ./start-tc-server.sh -f <path/to/server/config>/tc-config.xml

Note

You will need to have JAVA_HOME set to JDK8 while starting the Terracotta server.

Check for the below INFO log to confirm if the server started successfully, Terracotta Server instance has started up as ACTIVE node on 0:0:0:0:0:0:0:0:9510 successfully, and is now ready for work.

Not quite ready yet?

Read the user documentation for everything you've been wondering about the new API!