Saturday, March 27, 2010

Clustering A Grails App with Terracotta

When I was writing Grails: A Quick-Start Guide, I thought that scalability issues were too complicated and “out of scope” for a “getting started” book. Well, the folks at Terracotta have been busy at work making me wrong. Integrating Terracotta's Web Sessions clustering product is so easy that I could have covered it in a page or two. So, we'll do that now.

In this post, we'll install and configure Web Sessions Express. In subsequent posts we'll look at some of Terracotta's other products: EhCache, Quartz, and EhCache for Hibernate.

We'll start with installing Terracotta, which can be downloaded at We'll grab the tar/zip file (terracotta-3.2.1.tar.gz) and expand it to an appropriate location (like /opt/terracotta-3.2.1/). Then we'll set that directory as our TERRACOTTA_HOME.

Included with the install is a JAR file that will be used by our server. The exact location where we copy this file varies by server. We'll be using Tomcat 6.0.24, so we'll follow the instructions for Tomcat 6.0x. Let's copy TERRACOTTA_HOME/sessions/terracotta-session-1.0.0.jar to CATALINA_HOME/lib. (For the correct location for other servers, see the Terracotta documentation.)

Now for our application, we'll use the version of TekDays from the final chapter (Deployment and Beyond) of GQuick. If you worked your way through the book, you know that this application is going to be so popular that we're going to have to deploy it on a whole bunch of servers. :-) If you didn't build the application, you can download it from Also, check out this post on upgrading and deploying TekDays for some helpful tips.

Next we need to add a very simple configuration file to our application. We'll create the file web-app/META-INF/context.xml and include the following bit of XML:


<Valve className="


I've suggested that the Terracotta team come up with a Groovy DSL for configuring their tools in Grails applications, and it seems that they're considering it. But in the meantime, take the necessary precautions when you're adding the XML, and be sure to take a break and bandage any wounds you received through handling those sharp edges.

Note that these instructions are for deploying to a Tomcat server in the 6.0x family. If you are using an older version of Tomcat or if for some strange reason <grin> you are using some other server, you can find the appropriate configuration code at the documentation page.

We're almost done. Right now we could start up the Terracotta server, start up our Tomcat server, and deploy a TekDays.war. And it would almost work. But in order for Terracotta to cluster an application, all of the artifacts that we want to be clustered need to implement serializable. So, we'll just open up some of our classes and add implements serializable to their class declaration. Here's a list of the files that we need to modify:








For example, we'll modify the TekEvent class like so:

class TekEvent implements Serializable {

We'll do the same for each of those other files, and then we'll be ready to try it out. To run our newly terracottafied TekDays application, take the following steps:

1. Build a WAR file: from the TekDays application directory, run grails war tekdays.war

2. Copy tekdays.war to Tomcat's webapps folder: /webapps

3. Start the Terracotta server: /bin/ (or .bat if you're on Windows)

4. Start Tomcat: /bin/ (or .bat if you're on Windows)

5. Quick sanity check: navigate to http://localhost:8080/tekdays (or the port that your Tomcat instance is running on.)

6. Start the Terracotta Developer Console (this step isn't necessary to run the app, but it gives us a nice way to see that it's working): /bin/ (again .bat if you're on Windows)

The Developer Console will give us a screen like this:

When we click "Connect", we should get something like this:

Now this only shows one connected client right now, since that's all that we're running. To really see the magic, we need to fire up another Tomcat instance on a different port. But we'll leave that as an exercise for the reader.

There is one simple thing we can do to catch a glimpse of what Terracotta is doing for us. With TekDays running, navigate to a page – maybe create a new event and start adding some tasks. OK, now leave that page up, go to the console, and shut down the Tomcat server: /bin/

Let the shutdown finish, and then restart Tomcat. Give that a minute to wake up, then go back to the page and continue what you were doing. Everything is just as you left it. The logged in user is even in the session! Pretty slick!

There are other steps for setting up multiple Terracotta servers and such, but as far as our application goes, that's all there is to it. If I ever get a chance to write a second edition of Grails: A Quick-Start Guide, there will definitely be a section on scalability. Because, as we all know, Grails Scales!

Thursday, March 25, 2010

Upgrading and Deploying GQuick Code

Several people have gone through the sample application from GQuick using more recent versions of Grails (1.2 and 1.2.1), and it all seems to work, with one exception. If you use packages, as Grails 1.2 and above encourage you to do, one of the plugins (the Blurb plugin) will fail. I've been in contact with the plugin's author and he promises to fix that soon.

On the other hand, if you didn't build the TekDays application but would like to work with the code downloaded from the Pragmatic Programmer's website, there is a different issue. I recently downloaded the final code base, which is found in the download bundle at code/deploy/TekDays/, and upgraded it to Grails 1.2.1. I ran into a conflict with two versions of the Bubbling plugin. It appears that the upgrade process pulls down the newer version of the Bubbling plugin (2.1.1), but the old version (1.5.1) was still installed. The solution (or at least a solution) was to go to home/.grails/1.2.1/projects/TekDays/plugins/and remove the 1.5.1 version of the plugin. After that it all worked fine.

It worked fine, that is, until I tried to deploy the app to Tomcat. When I built the .war file and copied it to my /webapps/ directory, it wouldn't start. I tried forcing it to start from the Tomcat manager. No dice. So I checked in /logs/catalina.out (if you're using Tomcat, you gotta love that file), and found a datasource error that made me smack my forehead.

In the last chapter of GQuick, we look at how to configure a Grails application to use a JNDI datasource, which is a good idea for a real production deployment. But you may not have JDNI configured on your local Tomcat instance; I sure didn't. So, I changed my grails-app/conf/DataSource.groovy file to make the production datasource the same as development.

If you are doing this for the first time and haven't worked through the book, you will need to create a MySQL database called tekdays and set the user and password to match that in the DataSource.groovy file (or vice versa). Alternatively, you can use any database with a JDBC driver. Just include your JDBC driver in the TekDays/grails-app/lib/ directory and modify your DataSource.groovy accordingly. I prefer MySQL because it's so easy to get and easy to use. (More info on MySQL can be found at

One final note: Some people have mentioned getting OutOfMemoryErrors when deploying the app to Tomcat. This can happen with any Grails app if the JVM memory settings are too low. To prevent this, you can add (or modify) a JAVA_OPTS environment variable. In Linux/Unix or Mac OSX, you could do something like this:

export JAVA_OPTS='-Xmx1G -XX:MaxPermSize=256m'

In Windows, you can use the wizard in the control panel under System. Or maybe you can edit your autoexec.bat file. (Do they still use that?)

For the best learning experience, it's probably worth the time to go through the book and build the app as you go, but if you want to just download it and take it for a spin first, these tips should help you get going.

Have fun!