Basic Apache Tomcat clustering for Grails applications

posted by pledbrook on July 20, 2010 06:43 AM

Grails is a rapid application development framework for web applications on the Java platform. It's similar in many respects to Ruby on Rails, but it's based on Java libraries, like Spring and Hibernate, and the Groovy language. It also produces standard WAR files that can be deployed to a servlet container like Tomcat. That means you can deploy Grails applications to a Tomcat cluster and in this article I'll show you how.

Getting started

In order to demonstrate clustering, we need an application to deploy. Assuming that Grails is installed (I was using Grails 1.3.3 - the latest) we can create a brand new application with the command

grails create-app my-cluster-app

This will create a my-cluster-app directory containing the project. If we then switch to that directory, we can generate a WAR file straight away by running

grails war

Of course, the application doesn't do anything yet. Nor is it ready for clustering.

Those in the know are aware that a Java web application can't be clustered unless it is marked as 'distributable' and Grails applications are not by default marked as such. The easy solution is to add the <distributable/> element to the web descriptor, but you won't find a web.xml file in a standard Grails application. That's because Grails generates the web descriptor on the fly when it needs one. Fortunately, a web.xml that you can edit is only a command away:

grails install-templates

This will install several template files in your project, but the one we're interested in is src/templates/war/web.xml. Open this up and add the <distributable/> element:

<web-app ...>
  <!-- Add this line -->

Now when Grails generates the WAR file, the web application will be distributable.

It would be great if this was all we needed to do to make a Grails application ready for clustering, but that bane of deployments everywhere, configuration, must be tackled first. In a standard Grails application, the relevant files are packaged with the WAR file. This is convenient for development since you don't have to worry about managing external configuration files and their locations, but it prevents you from customising the configuration per deployment. What's the solution?

Local configuration

There's no getting away from the fact that the simplest way to provide per-deployment configuration is via external configuration files located on the deployment servers. This allows you to reconfigure the application at any time with a quick edit and server restart rather than a redeployment of the WAR. Grails allows for external configuration files through a special grails.config.locations setting in the grails-app/conf/Config.groovy file:

grails.config.locations = [ "file:./${appName}-config.groovy", "classpath:${appName}-config.groovy" ]

This tells Grails to load two configuration files, one from the local filesystem and one from the classpath. Why the reference to 'appName'? It's so that you can easily host multiple web applications on a server/cluster without the names of the configuration files conflicting with each other. At runtime, ${appName} is replaced by the name of the application, i.e. the name passed to the create-app command - 'my-cluster-app' in this case.

The first path is for development when you're executing grails run-app - the configuration file just goes in the root of the project. The second item is for WAR deployment and causes Grails to look for the file on the classpath. You often don't know at development time where the current working directory is or where configuration files go on the deployment server's file systemm. So where can you put the configuration file so that it goes on the classpath? Since Tomcat add its lib directory to the classpath, that's the ideal location. Don't worry if Grails can't find one or other of the specified files: it will simply print a warning to stderr but continue to start up normally.

We'll return to these configuration files and what to put in them later when we come to the actual deployment. That story isn't over yet. For now, I want to consider features that would be affected by clustering, such as caching, scheduling, etc. It's easy to overlook them because Grails typically makes it very easy to include features without explicit configuration, but if you deploy to a cluster with their default settings, they will typically break.

Distributed caching

When you first create a Grails application, it has Hibernate's 2nd-level cache already enabled and configured to use Ehcache. You can take a look at the grails-app/conf/DataSource.groovy file to confirm this - you should see the following:

hibernate {
    cache.use_second_level_cache = true
    cache.use_query_cache = true
    cache.provider_class = 'net.sf.ehcache.hibernate.EhCacheProvider'

As you can see, it configures Ehcache as the cache provider. What you won't see is an Ehcache configuration file (ehcache.xml) in the project. That means Ehcache will use its default settings. This isn't recommended for a standalone server, let alone a clustered one. An additional concern is that Ehcache should be configured differently for local development (using grails run-app) and deployment to the cluster. How do we manage that?

Ehcache will load the ehcache.xml file from the classpath. We can easily make sure that the file ends up on the application's classpath by placing it in either the grails-app/conf or src/java directories. The trouble is, that file will be used in both development and the deployed web application. If you want different files for development and deployment you have to resort to a clever trick: replacing the file at packaging time.

The Grails build system allows the developer to interact with the build via an event system. One of those events is triggered just before the WAR is created, which allows us to influence what goes into the final package. All we have to do is create a scripts/_Events.groovy file containing this code:

eventCreateWarStart = { name, stagingDir ->
    ant.copy(file: 'cluster_resources/ehcache_distributed.xml',
             tofile: "$stagingDir/WEB-INF/classes/ehcache.xml", overwrite: true)

This event handler will copy the distributed cache configuration file from the cluster_resources directory to the staging directory, replacing the standard ehcache.xml. Once its done, Grails zips up the staging directory as the WAR file. Job done. Note that cluster_resources is not a standard Grails directory, so it must be created manually. You can find it along with the Ehcache configuration files in the attached project.

Caching isn't the only case where you have to do something special for cluster deployment, but external configuration files and tinkering with the generated WAR file will typically work for other cases as well. For example, you can use the same technique we used for ehcache.xml to ensure that an appropriate file (if you're using Quartz) is used by the application on the cluster.

We're now almost ready for deployment, but we don't yet have a way to test the session replication. For that, we need some web pages that utilise the HTTP session.

Creating the test pages

This being Grails, creating test pages is straightforward. We're going to use a single controller with three actions (which correspond to three distinct pages): 'arrive', 'leave', and 'counter'. Create the file grails-app/controllers/HomeController.groovy and give it this content:

class HomeController {
    def arrive = {
        if (session.counter) {
            render "You are already here"
        else {
            session.counter = 1
            render "You have arrived - counter initialised"
    def leave = {
        if (!session.counter) {
            render "You have already left"
        else {
            session.counter = null
            render "You have left - counter cleared"
    def counter = {
        if (session.counter) {
            render "Counter: ${session.counter}"
        else {
            render "You're not here!"

When we hit the page /home/arrive the counter variable will be added to the session. This counter will then be incremented and displayed each time we go to the /home/counter page. Finally, the variable is removed from the session when we hit /home/leave. Simple, pointless, but it does demonstrate the session behaviour of the application. We can now run the grails war command to generate a WAR file.


Now that we have a WAR file, we can focus on deploying it to a Tomcat cluster. It's not the focus of this article to detail how to set up a Tomcat cluster, but in case you haven't done it before I have attached a package of scripts based on Burt Beckwith's work and using Tomcat 6.0.28. Just download the archive and unpack it to any directory, for example in ~/tomcat-cluster-scripts. In the root of the archive you will see several shell scripts which make creating and managing a Tomcat cluster almost trivial.

Let's start by creating a cluster in a /opt/java/tomcat-cluster directory:

cd ~/tomcat-cluster-scripts
export CR=/opt/java/tomcat-cluster
sudo ./ my-cluster-app

This will create a cluster for the application 'my-cluster-app'. You can pass the location of the cluster to all the scripts, but it's easier to create a CR environment variable containing the location and run the scripts without that argument. Saves typing! Our cluster is now ready and all we need to do is add some Tomcat instances:

sudo ./ 1 1
sudo ./ 1 2

These commands will create two instances (1 & 2) on server 1 - the first argument being the server number, the second argument the instance number. You can find the instances at $CR/instance_1 and $CR/instance_2. In this example, I'm only creating a single server cluster, but you can run the scripts on multiple servers to create a multi-server cluster - just make sure you use a different server number on each one. As a side note, the scripts only work if you use single digit numbers for the instance numbers, so don't try to create more than nine instances on a server with them!

Before we start the Tomcat instances, we must first deploy our application and configure it. For the physical deployment, we can use the script:

sudo ./ /path/to/myapp-0.1.war

This will unpack the WAR into the $CR/shared/webapps/ROOT directory, so the application will be served from the root context. This makes it easier to load balance the application with something like Apache httpd. The next step is to configure the database and logging for our instances. If you look in the $CR/shared/lib directory, you will see a my-cluster-app-config.groovy. What's this for? If you cast your mind back to earlier in the article, you will remember that we added the line

grails.config.locations = [ "file:./${appName}-config.groovy", "classpath:${appName}-config.groovy" ]

to the application's Config.groovy file. Since the shared/lib directory is on the classpath of all the cluster instances, we can add extra configuration via this my-cluster-app-config.groovy file. This could include database connection settings, logging configuration, or anything else. In this case, we'll configure the database connection settings and make sure that log files are created per instance. Open up the file up and add the following:

dataSource {
    dbCreate = 'update'
    username = 'grails'
    password = 'grails'
    driverClassName = 'com.mysql.jdbc.Driver'
    dialect = org.hibernate.dialect.MySQL5InnoDBDialect
    url = 'jdbc:mysql://localhost/myapp'
log4j = {
    appenders {
        rollingFile name: 'main', file: "${System.getProperty('catalina.base')}/logs/main.log"
    root {
        info 'main'

On the database side, the above configures all instances to use the 'myapp' MySQL database with the 'grails' user. Of course, you need the MySQL JDBC driver on the classpath, but that's as easy as copying the JAR into the shared/lib directory. On the logging side, we want to make sure that the application log file is created in the logs directory of each instance. Since the location of the instance directory is available in the 'catalina.base' system property, we can easily include it in the log file's path as we have done above.

Assuming that the MySQL database already exists, we're ready to test the cluster. Start the Tomcat instances with these commands:

sudo ./ start 1
sudo ./ start 2

After a little while you should be able to point your browser at http://localhost:8091/home/arrive and see the message "You have arrived - counter initialised". Now replace the 'arrive' in the URL with 'counter' and reload the page a few times. The counter will increment on each refresh. So that's the first Tomcat instance working. What about session replication? To test that, go to this URL: http://localhost:8092/home/counter - you are now hitting the second server. If everything is working properly, you should see the counter incremented from the previous number you saw - the session replication is working!

The next step would be to put a load balancer in front of the Tomcat cluster, but that's beyond the scope of this article. Suffice it to say that you don't have to do anything special for Grails applications. Should you choose to use Apache httpd with mod_proxy_balancer, you may be interested in the modproxybalancer Grails plugin which allows you to redeploy your application via a single Grails command, although you need to have Tomcat's manager application installed in all your instances.

Wrap up

Since Grails applications are packaged as WAR files, you can deploy them to a servlet container just as you would any other Java web application. That's one of the key strengths of Grails. Tomcat clusters are no different, but they do force you to do a bit more custom configuration of a Grails application than would normally be the case. As you've seen, this is straightforward using externalised configurations. When you need more flexibility, you can always make use of the Grails build system with its events or use JNDI.

I hope this post proves useful to both Grails developers who have never set up a Tomcat cluster and those people who have to deploy Grails applications in production systems. Although their configuration is different to typical Java web applications, once you know the techniques, it's pretty straightforward.

As a final note, I have made the sample application available to download.

I'm the Grails Advocate at SpringSource (a division of VMware) and one of the core committers of the project. I have been using Grails since 2006 and have contributed several plugins on top of the work I have done on the core. These days I write about the framework and guide people through basic and advanced usage.


It is nice to know about

It is nice to know about Grails applications. I usually try to learn various web applications based on joomla platform as it is easy to learn. But this one seems to have a large variant of applications in mobile as well as pc. I am always searching for such quality articles written in a great manner.
unfiled taxes

I prefer the submit. It

I prefer the submit. It really is excellent to find out an individual verbalize from your coronary heart and also quality with this crucial subject matter may be effortlessly witnessed.

very glad I found your site,

very glad I found your site, thanks for the post

Thanks so much for this

Thanks so much for this information. I have to let you know I concur on several of the points you make here taruhan judi bola and others may require some further review, but I can see your viewpoint.


Listed here you'll learn it is important, them offers the link in an helpful webpage:
wealth debt free


My partner and i examine your website on what to publish the particular and also My partner and i entirely adored that! After all, my own educators have got discussed the method if you ask me adequate instances yet no-one provides caused it to be appear since fantastic when you.ed reverser download


That i don’t fully understand once you discover any severity for assistance that personal blogs supply. In my opinion, I do know that this it all weren’t in your personal blogs We'd don't have uncovered that will help utilizing my best essays.Thank you so much! diabetes destroyer reviews


Looking through a person's blogs and forums would make people prefer to publish progressively more. I did so your we appeared to be really happy by using. Them aren't executed to the place nonetheless it’s striking. I'll give you actually the hyperlinks so you're able to look at them to do allow me to explain imagination.
obsession phrases reviews

Soy mi Contador - Contabilidad en línea

It is very good, but look at the information at this address.
contabilidad en linea para personas fisicas


Belonging to the start looking from your blogging, you have got possessed a relatively good go through through authoring.
ed miracle shake

cmx videomts

Software avchd converter convert avchd video files to avi, mp4, wmv, mov mod converter free download to convert HD camcorder files. mts to avi mp4 mov mkv iMovie, FCP/FCE with mts converter, so to convert mts files for your PC and mobiles. ew

Greg Insider Method Review

Very good topic, similar texts are GregInsiderMethodReview I do not know if they are as good as your work out.

Thanks for this great post, i

Thanks for this great post, i find it very interesting and very well thought out and put together. I look forward to reading your work in the future. go to

Platinum Profits

It is fine, nonetheless evaluate the information and facts around this correct.


Document was aware of the fact that impact was first only just all the foreign language benefit from it also yet seemed problematic. At this time it’s definitely do- effective. With thanks for those support.
Profit Magnet


One of the many blog sites using the net, I like perusing joining your the foremost; most people make available you and me such a lot of material within smallish section. I'm sure on the lookout for not to mention as there are a spirit for the purpose of helpful penning, I just determined you would purpose everybody in your best suited place. How can you guidance?


I want an individual's place. It is actually superior to observe everyone verbalize within the heart and soul together with readability on this subject necessary area are usually conveniently detected. facts observe webpage.
ed miracle

Where else could anyone get

Where else could anyone get that kind of information in such a perfect way of writing? I have a presentation next week, and I am on the look for such information.


Reading through your own weblogs can make me personally wish to create increasingly more.
vo genesis review


Checking any blog may make others just want to come up with a greater number of. I did a fabulous which i was first lovely content by means of. The software most likely conducted for the tier still it’s exceptional. I often dispatch you
0-6 pack abs review

Read more here: 192.168.l.l

Read more here: 192.168.l.l

Gives you the best website

Gives you the best website address I know there alone you'll find how easy it is. aventura locksmith

Great Article it its really

Great Article it its really informative and innovative keep us posted with new updates. its was really valuable. thanks a lot. mi40x

With so many books and

With so many books and articles coming up to give gateway to make-money-online field and confusing reader even more on the actual way of earning money, Hubwit is a refreshing change. I stumbled upon this site while searching for work-form-home options. red smoothie detox factor review

Consultant SEO Marseille

I came alongside your blog bit focusing righteous somewhat bends. Pretty method for adjoining, I pleasure be bookmarking at previously grab your full ascends...
consultant seo marseille

Zuckerpaste Sugaring Paste kaufen im Shop Haarentfernung mit den

I use only high quality materials - you can see them at:

Home | Payday Loans Canada | Same Day Faxless Cash Advance Till

I recommend only good and reliable information, so see it:
faxless padyay loans canada

Your blog won't render

Your blog won't render appropriately on my iphone - you may wanna try and repair that
Edmonton Mortgage Broker
Life Insurance Vancouver
Life Insurance Calgary

First You got a great blog .I

First You got a great blog .I will be interested in more similar topics. i see you got really very useful topics, i will be always checking your blog thanks. f4x any good rebelmouse

Bina Droid

This is important, though it's necessary to help you head over to it weblink:
Bina droid

Rock On - Supplements to Rock Your Mind, Body & Spirit

One of many blog sites on line, I like to browsing the ones you have just about the most; everyone supply individuals a huge amount of advice of hospitality attire minor article. My organization is in need of together with seeing that you now have a heart and soul meant for informative posting, That i worked you can actually issue my family during the ideal focus. Is it possible assistance? Best Testosterone Booster Supplements

Planet BomB

In this particular article, you will see a summary, satisfy browse this post.

One of many websites on the

One of many websites on the internet, I like to surfing around the ones you have just about the most; everyone provide people a large amount of recommendation of kindness outfit minimal content. My company is in need of together with seeing that you now have a core intended for useful publishing go to the website, That i proved helpful you can actually problem my family members during the perfect concentrate. Is it possible assistance?

My rather long internet look

My rather long internet look up has at the end of the day been compensated with pleasant insight to talk about with my family and friends

trade alerts

Easily this page will probably unquestionably possibly be well known involving many blogs persons, for its meticulous articles or blog posts or maybe opinions. trade alerts

One of many sites on the

One of many sites on the internet, I like to shopping the ones you have just about the most; everyone offer people a lot of suggestions of goodness clothing little material. My organization is in need of together with seeing that you now have a primary designed for useful posting go to the web page his comment is here, That i performed you can actually issue my individuals family members members during the ideal focus. Is it possible assistance


I want an individual's place. It is actually superior to observe everyone verbalize within the heart and soul together with readability on this subject necessary area are usually conveniently detected. facts observe webpage. forsit


I'm keen a put up. It happens to be fantastic to ascertain most people verbalize out of your spirit not to mention ability on that fundamental topic area are generally comfortably found. ideas viewpoint online site. forsit

Ulje Tamjana

It is delighted to read this post and i get many useful point through this post. Please keep posting such kind of post ulje tamjana

Buy Facebook Likes

I love your own publish. It's great to determine a person explain in words in the center as well as clearness about this essential topic could be very easily noticed. more information look at website. Buy Facebook Likes


The level of pick around to provide a blog? A colleague noted the is without a doubt a technique in selecting decent tailor-made article online sites. Is without a doubt this a reliable form? GPS dog collar


Your website posting around the like factor! I recognize the following company this made it simpler for people publish a possibly! Get real, the key reason why will need to we will have to go through endeavoring to publish these folks our-self if there are actually industry experts nobody can enable united states along? I actually express, make these folks enable. otoplasty london


That might get the job done short-term, though it’s a fantastic good long-term treatment designed for gentlemen who wish to end up one of the keys you extraordinary daughter some people can’t discontinue making plans for. kiseonik

My rather long internet look

My rather long internet look up has at the end of the day been compensated with pleasant insight to talk about with my family and friends


Ski boots for ladies function similarly as it will be possible ski boot footwear do. But its composition plus designing methods are usually different. Girls ski boot footwear are marginally leaner around cuff levels, contouring and get thick pillow for improved foothold. andrew murray

wow, great, I was wondering

wow, great, I was wondering how to cure acne naturally.


I've got to look for internet sites using pertinent home elevators granted theme and still provide the crooks to tutor each of our thoughts and opinions plus the content. delete kik account


Checking any blog may make others just want to come up with a greater number of. I did a fabulous which i was first lovely content by means of. The software most likely conducted for the tier still it’s exceptional. best web design firms


I've got to look for internet sites using pertinent home elevators granted theme and still provide the crooks to tutor each of our thoughts and opinions plus the content. dapoxetine and sildenafil citrate

This keeps your very own

This keeps your very own price of metabolic process up and also will enhance the rate of physical body weight loss. Normally men and also females learn more stamina throughout the day as well. red smoothie detox

Post new comment

This question is for testing whether you are a human visitor and to prevent automated spam submissions.