I’ve recently been looking into Terracotta to enable session replication in one of our products. In order to get a deeper understanding, it seemed logical to try and set it up myself. It’s really useful to get your hands dirty, see how the Operations team work – this gives you a better perspective of what the installation and configuration involve. It’s no use developing software and letting someone else take care of the rest, today’s organisations need people who can break-down boundaries, not stick their head in the sand. Besides, it leads to a better understanding of the systems that comprise your entire architecture.

Using the Amazon’s EC2 Cloud seemed like a perfect fit for a short term experiment like this. The approach was to start at the easiest parts and gradually add complexity until we had Tomcat offloading session storage to the Terracotta cluster.

The basic steps were to:

1. Launch an EC2 server instance
2. Perform a basic Tomcat installation
3. Install Terracotta on the same instance and re-configure Tomcat
4. Rinse and repeat to add a second Terracotta instance to the cluster

Launch an EC2 server instance

Start by firing up a t1.micro instance using the Amazon Linux AMI. If you’re using the Amazon EC2 command-line tools, start the instance and then check it has started correctly using these commands.

ec2-run-instances ami-3ac33653 -n 1 -g default -k [keyname] -t t1.micro
ec2-describe-instances

Login to the instance using your favourite SSH client, but make sure that the SSH key specified in the ec2-run-instances command is being used.

Basic Tomcat installation

This AMI already has Java installed (an OpenJDK version), so installing Tomcat simply requires a download of the software, unpack and run the startup script. Make sure that the Amazon Security Group used to start the instance allows access to the Tomcat port (default 8080) on the instance.

Accessing the public DNS name of the Tomcat server should show you the default Tomcat homepage. You can retrieve the public DNS name for any instance in the AWS Management Console.

Terracotta and Tomcat

The open source versions is available from Terracotta downloads.

Following the web sessions install:

1. Extract the Terracotta software
2. Copy the Terracotta jars (terracotta-session-1.1.1.jar, terracotta-toolkit-1.1-runtime-2.0.0.jar) into the $TOMCAT_HOME/lib directory
3. Add a Terracotta configuration (here’s an example) and use the $TERRACOTTA_HOME/bin/start-tc-server.sh to fire up Terracotta and start tailing stdout
4. Add a Valve to the Tomcat context configuration letting Tomcat know to load the Valve and Terracotta config from the URL provided

<Valve className="org.terracotta.session.TerracottaTomcat60xSessionValve" \
    tcConfigUrl="ec2-xx-xx-xx-xx.compute-1.amazonaws.com:9510" />

From your machine, you can fire up the Terracotta Developer Console using the bin/dev-console.(sh|bat) script, but it will be necessary to allow connections to ports 9510, 9520 and 9530. The server host will be the same DNS name used in the tcConfigUrl and port 9530. When starting Tomcat the catalina logs should show that Tomcat has successfully loaded the configuration and the Developer Console will display the sessions in the tree menu on the left.

Add a second Terracotta instance

Launch a second instance, add the Terracotta software, open the required ports (9510, 9520 and 9530; they should be open to each other and to your machine to use the Dev Console) and launch the startup script – you are almost there.

Each of the Terracotta configuration files will need both servers listed (using the same names, in the same order) and then require a restart.

This example is a single server array and provides reliability and failover. For scalability, you will need to add multiple mirror groups.

Gotchas

• You can now stop/start the Terracotta instances indepently and the ACTIVE CO-ORDINATOR role will change. When a server is rejoining, it may complain that it has a dirty cache and that it needs to be manually cleaned up. This can be done by removing the terracotta/server-data directory and then restarting it.
• If the server listed in the Valve configuration is no longer the co-ordinator and Tomcat is restarted, the Tomcat server will not be able to load the config file. Only the co-ordinator seems to answer to this request from Tomcat. Using Elastic IPs to map the current co-ordinator could be a solution for this.
• Make sure you use the external DNS name in the Terracotta configurations if you wish to interrogate them with the Developer Console. The console will obtain the configuration file from the node it connects to, but if the addresses used are not routable from where the console is running you won’t get any results.