Configuring Your Environment
After you have installed the product as described above, there are various configuration activities that you will need to perform in order to set up the product environment and to run your application(s).
The installed API client jars need to be embedded in a customer application before they can run.
We suggest that you proceed as follows:
1. Familiarize yourself with the general concepts of the product.
For an overview of Terracotta, see the document About Terracotta.
For an overview of Terracotta Ehcache, see the document About Terracotta Ehcache.
2. Familiarize yourself with all the system requirements and recommendations.
In particular, considerations concerning deployment, storage hardware and using virtual machines should be evaluated according to what is recommended in the relevant sections of this documentation.
Further reading:
3. Configure the Terracotta Server to define the offheap memory resources that you will use, and the size of each storage tier. This involves setting up an XML-formatted configuration file that contains all of the properties to define the configuration of the Terracotta Servers in a stripe.
For details, see the section The Terracotta Configuration File in the document Terracotta Server Administration Guide.
If you intend to use a high availability (HA) topology, you need to consider how your application values data consistency versus availability.
See the section
Failover Tuning in the
Terracotta Server Administration Guide.
For various examples and explanations, check through the Ehcache API Developer Guide and TCStore API Developer Guide.
4. Start the Terracotta Server.
Terracotta servers can be started without the need for the cluster tool to have run, but cannot be used until the cluster tool has been run.
5. If you intend to use a high availability (HA) topology, you can start several instances of the Terracotta Server one after the other, all using the same configuration file. Such a group of servers is termed a stripe. In a stripe, one of the servers becomes the active server and the others become passive servers. A stripe can also consist of just an active server and no passive servers.
6. To use Terracotta clustering features in your client applications, you will need to use the Cluster Tool to set up the cluster.
Whenever active and passive servers are running on one or more machines, the cluster tool can be used on one of the machines to create a cluster.
For a general overview of clustered caches, see the section
Clustered Caches in the Ehcache API Developer Guide. For an overview of the cluster tool, see the section
The Cluster Tool in the document
Terracotta Server Administration Guide.
7. Develop your caching application(s) using the TCStore API or the Ehcache API.
See the Ehcache API Developer Guide for details of how to develop caching applications using the Ehcache API.
See the TCStore API Developer Guide for details of how to develop caching applications using the TCStore API.
8. Start your client application(s).
9. Check the status of the running system, such as which applications are running, which caches are in use, cache usage metrics etc., by using the Terracotta Management Console (TMC).
Overview of Command Line Scripts
The distribution kit contains command line scripts that you can use to start and stop various components of the Terracotta environment. The table below lists the scripts that you will probably use most frequently. The file type of the scripts is ".bat" for Windows or ".sh" for UNIX-based systems.
Script | Description |
server/bin/start-tc-server.bat(.sh) | Start the Terracotta Server. The Terracotta Server provides the distributed data platform for Terracotta products. |
tools/cluster-tool/bin/cluster-tool.bat(.sh) | Run the cluster tool. The cluster tool is a command line tool that allows you as an administrator of the Terracotta Server Array (TSA) to perform a variety of tasks in the area of cluster management. |
tools/management/bin/start.bat(.sh) tools/management/bin/stop.bat(.sh) | Start or stop the Terracotta Management Console (TMC). The TMC is a graphical web-based application for managing and monitoring your Terracotta Server Array and connected clients. |
A Note on Working with VMware vMotion
Software AG strongly recommends against allowing live migrations of virtual machine(s) with Software AG Terracotta server processes. This is because of the downtime introduced during the live migration process which can cause other Terracotta server processes to elect a new active server which will then create data consistency problems (such as split-brain scenarios) when the migrated process becomes live again.
If you must use vMotion in your environment, please make sure that Terracotta server processes and runtime processes are excluded from live migration. Be very thoughtful about any other VMs that you put on the same hardware - the workload within it may be disruptive to the resources available to the Terracotta server.
Applications utilizing Terracotta (Terracotta clients) can also experience disruption by live migrations - although they will normally automatically reconnect and resume operation in a healthy and well-resourced virtualized environment.