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.
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 a config file that defines a common configuration to be used for all the servers in a cluster.
For details, see the section The Terracotta Configuration File in the document Terracotta Server Administration Guide.
Note:
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.
You can start Terracotta servers before you run the config tool. Upon startup, you need to run the config tool to activate the cluster and make it usable by Terracotta clients.
5. If you intend to use a high availability (HA) topology, you can start a group consisting of several instances of the Terracotta Server one after the other, in a so-called stripe. In a stripe, one of the servers becomes the active server and the others become passive servers. The active server is the only server in a stripe that can participate in a cluster. If the active server fails, one of the passive servers will take over as the new active server in the stripe. 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 config tool to set up the cluster.
Whenever active and passive servers are running on one or more machines, the config 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 config tool, see the section
The Config 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/bin/cluster-tool.bat(.sh) | Run the cluster tool. The cluster tool is a command line tool that allows an administrator of the Terracotta Server Array (TSA) to perform a variety of tasks in the area of cluster management. |
tools/bin/config-tool.bat(.sh) | Run the config tool. The config tool is a command line tool that allows an administrator to set up, activate or modify the configuration of the cluster. |
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. |
Additionally there are tools under tools/upgrade/bin for upgrading to the new product version from a previous product version. The upgrade procedure covers aspects such as:
converting existing data to the format required in the new version.
converting configuration files to the format required by the new version.
Note:
In versions before v10.7, there was one configuration file per stripe, whereas from v10.7 onwards there is one configuration file that applies to all servers in a cluster.
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.