Choose a TC quick start guide depending upon your version:
Getting Started With TC Server 4.3.x
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.shFor Windows systems:
> cd \path\to\terracotta-<version>\server > .\bin\start-tc-server.batYou 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 with TC Server 5.5/10.5
Getting started with the Terracotta Server 5.0/10.0 through 5.5/10.5 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 one of its most common uses: 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 anehcache.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 withCache
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 atc-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 haveJAVA_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!Getting Started with TC Server 5.5/10.5
Getting started with the Terracotta Server 5.0/10.0 through 5.5/10.5 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 one of its most common uses: 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 anehcache.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 withCache
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 atc-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 haveJAVA_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
.