Richard Wilkinson’s Blog

How to run terracotta as a service

I’ve blogged about terracotta before and if you want to find out more about it I suggest you start on their website.

One thing that terracotta doesn’t provide out of the box is a way of running as a background service. While it is pretty easy to run the command in the background with a combination of & and nohup on linux e.g.:

~> nohup start-terracotta-command.sh &

However this doesn’t provide all of the functionally that you might want, like automatic restarts or remote management with JMX. It also doesn’t work on windows (if you care about that).

Luckily it is pretty simple to integrate terracotta with the java service wrapper which is an open source library to run any java program as a service. These are the steps I used to get it working:

1. Create an environment variable that points to your terracotta install directory, I use $TERRACOTTA_HOME.
2. Extract the correct version of the service wrapper for your platform inside $TERRACOTTA_HOME, my version was wrapper-linux-x86-32-3.3.0.
3. Edit your $TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/conf/wrapper.conf so it looks something like this:

   wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
   
   wrapper.java.classpath.1=../lib/wrapper.jar
   wrapper.java.classpath.2=../../lib/tc.jar
   
   wrapper.java.library.path.1=../lib
   
   wrapper.java.additional.1=-server
   wrapper.java.additional.2=-Dcom.sun.management.jmxremote
   wrapper.java.additional.3=-Dtc.install-root=../../
   
   wrapper.java.initmemory=256
   
   wrapper.java.maxmemory=256
   
   wrapper.app.parameter.1=com.tc.server.TCServerMain
   wrapper.app.parameter.2=-f ../../tc-config.xml
   
   wrapper.logfile=../logs/terracotta.log
   

   Of course you can customise most of these options fit your requirements (for example memory options or log file) or add additional parameters. Also in the conf file there are other options which you may want to look at such as logging level.

4. Edit your $TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/bin/testwrapper so it looks something like this:

   APP_NAME="Terracotta 2.6.2"
   APP_LONG_NAME="Terracotta 2.6.2"
    
   WRAPPER_CMD="$TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/bin/wrapper"
   WRAPPER_CONF="$TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/conf/wrapper.conf"
    
   PIDDIR="$TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/"

5. You should also rename $TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/bin/testwrapper to a sensible name e.g. $TERRACOTTA_HOME/wrapper-linux-x86-32-3.3.0/bin/terracotta-wrapper.
6. You can optionally move this terracotta-wrapper file to a different location, for example /etc/init.d/ on linux.
7. Thats it. To run use this:

   /etc/init.d/terracotta-wrapper start

   To stop use this:

   /etc/init.d/terracotta-wrapper stop

   You can use ‘restart’ to stop and start the service, ’status’ to see the status of the service and ‘dump’ to take a thread dump of the running java program.

8. Anything sent to System.out will be logged to the text file defined earlier (wrapper.logfile)

These instructions are only the basic ones needed to get up and running and I recommend that you read through the service wrapper docs so that you get the system that fits best with your requirements.

Please let me know if this is of some use to you, or if you have any other ideas on how to run terracotta as a service.

Tags: service, terracotta