Open BlueDragon + Railo + ColdFusion on Tomcat | Matt’s excellent article

As a corollary to Sean’s post about running Railo, OpenBD, and ColdFusion on JRun, I thought I’d outline my preferred development environment these days, which is to run all the necessary CFML engines on Apache Tomcat. Note that this approach will work equally well on Jetty, JBoss, GlassFish, or more or less any servlet container or JEE server you choose.

Great minds think alike because coincidentally enough, Dave Shuck also has just published two blog posts (part 1, part 2) about setting up a similar environment. I figure I’ll throw mine out there as well because the more information available the better.

So why not use JRun? Well, aside from the fact that JRun is getting very long in the tooth at this point, personally (and you’ll probably hear me say this in a couple of conference presentations this year), I think the ColdFusion model stands Java on its head a bit, particularly when you do a standalone install of ColdFusion. Yes, it makes it easy to install and configure ColdFusion, but in my opinion it also shields people from how Java web applications actually work, so I’ve become a big fan of treating ColdFusion like what it is: a Java web application.

This to me makes far more sense than letting ColdFusion and JRun dictate your Java environment. And I think you’ll see in this blog post that “installing” CFML engines on Tomcat is actually easier than installing ColdFusion. The only even remotely tricky part is installing Tomcat (and in most cases it isn’t tricky at all), so let’s tackle that first.

As an aside, if you just want to try Open BlueDragon and don’t want to bother with the Tomcat installation, just download the Ready2Run Jetty + OpenBD distribution, start Jetty, and you’re done!

Installing Tomcat

I’m assuming you already have Java installed, and I recommend Java 1.6 updater 10 or later (updater 11 is the latest) since previous versions had a bug that makes CFC instantiation horrendously slow. So, if the following looks complicated, it’s really only because I’m outlining how to get the Java settings correct if you need to worry about it. Chances you won’t need to do most of these steps, and once Tomcat’s running the CFML piece of this puzzle is dead simple.

First, download Tomcat. As of this blog post the latest version is 6.0.18, and you’ll want the “Core” binary distribution. After the download completes, unzip the file you downloaded. Now comes the tricky install process. Oh wait, I forgot–there is no install process! All you have to do is start Tomcat after you unzip it. If you have your Java environment set up correctly Tomcat should find Java fine and fire right up.

To start Tomcat, open a terminal (or DOS window if you must …) and navigate to your Tomcat directory, then the bin directory. For example if you unzipped Tomcat to /home/yourname/apache-tomcat-6.0.18, you would navigate to /home/yourname/apache-tomcat-6.0.18/bin. (Note that all of this runs perfectly well on Windows, and though I would never recommend using Windows for anything, you do not have to use Linux to get any of this to work.)

Once you’re in the bin directory, run the script (./ and you’ll see some output similar to this:

Using CATALINA_BASE:   /home/mwoodward/apache-tomcat-6.0.18

Using CATALINA_HOME:   /home/mwoodward/apache-tomcat-6.0.18

Using CATALINA_TMPDIR: /home/mwoodward/apache-tomcat-6.0.18/temp

Using JRE_HOME:       /usr/share/java/jdk1.6.0_11

As long as you see something similar everything’s likely fine. If you see errors, the most likely culprit is that Tomcat can’t find Java. You can either set a JAVA_HOME environment variable, or you can explicitly tell Tomcat where to find Java by adding the JAVA_HOME location to the script in the bin directory. Open in your favorite text editor, and after the big block of comments at the top of the file (denoted with # signs), add the following line:


Note that this should be the path to your JDK’s home directory, not to a directory such as lib, etc. inside the directory. In my case I have Java in /usr/share/java/jdk1.6.0_11 so that’s the value I use for JAVA_HOME. Save and run again and everything should work now.

Check to make sure Tomcat is running by browing to http://localhost:8080 You should a page confirming that Tomcat is configured correctly.

Installing Open BlueDragon

Once Tomcat is running, since Open BlueDragon is a standard Java WAR (web application archive) file, “installing” OpenBD on Tomcat really just means copying a file to Tomcat’s webapps directory so the WAR file is deployed. A WAR file is actually the same format as a JAR file (which is essentially a ZIP file …), but it has an XML file that tells servlet containers how to deploy the application.

Here are the installation steps for OpenBD:

  1. Download the Open BlueDragon WAR (“J2EE Standard WAR”) file from
  2. Copy the WAR file (which unless you change it is called openbd.war) to /path/to/tomcat/webapps
  3. Wait a few seconds for Tomcat to auto-deploy the WAR file, and browse to http://localhost:8080/openbd to see a test page:
  4. That’s it! You now have Open BlueDragon running on Tomcat. Tomcat will deploy the WAR into a context path with the same name as the WAR file, which in this case is openbd, hence the URL http://localhost:8080/openbd If you want to deploy another instance with a different context path name, just change the name of the WAR file as you copy it (e.g. cp opendb.war /path/to/tomcat/webapps/mynewcontextpath.war) and you’ll have another instance with a different context path.

    As for where to put your CFML files, just put them in /path/to/tomcat/webapps/openbd (or whatever you called your context path), and of course all URLs for this instance will include the context path in them. I won’t be covering how to run Tomcat on port 80 or hook things into Apache in this blog post, but I’ll cover that in a future post.

    Installing Railo

    To install Railo you follow the exact same steps as above with Open BlueDragon:

    1. Download the Railo WAR from — you want the WAR file under “Railo Custom” at the bottom of the page
    2. Copy the WAR file to /path/to/tomcat/webapps. In this case since the file name includes the version number, I did a cp railo- /path/to/tomcat/webapps/railo.war, which will make the context path “railo”
    3. Wait a few seconds for Tomcat to auto-deploy the WAR file, and browse to http://localhost:8080/railo to see a test page:
    4. As with OpenBD above, just put your CFML files in /path/to/tomcat/webapps/railo to run them on Railo in the railo context path.

      Installing ColdFusion

      ColdFusion is a bit of a different beast since Adobe doesn’t distribute a standard WAR file, but luckily you easily can generate one by running the installer. The steps below are when you run the installer on Linux but the same principles apply on other operating systems. Let’s generate a WAR file for ColdFusion.

      1. If you don’t have it handy, download the developer edition of ColdFusion from
      2. Run the installer (note on Linux you need to run the installer as root)
      3. Accept the license agreement (which is really fun to page through on the console installer–I think if you hit enter 28 times that will get you to the “Do you accept?” prompt 😉
      4. Select Developer Edition (or use a serial number if you prefer)
      5. KEY STEP: Choose an installation type of “J2EE Configuration (WAR file)”
      6. Select the stuff you don’t want to include in the installation. I typically uncheck all four choices (docs, LiveCycle, search services, and start on init) when I generate a WAR
      7. Choose the installation directory or accept the default
      8. Enter the admin password
      9. Choose to enabled or disable RDS. I find it’s handy to have RDS on development instances so you can use the Eclipse tools to interact with the datasources.
      10. Enter the RDS password
      11. Confirm the installation selections and continue
      12. Wait a minute or so for the WAR to be generated
      13. At the end of this process you have a CF 8 WAR file sitting in your install directory (which by default on Linux is /opt/coldfusion8). Now the installation is more or less as above with OpenBD and Railo since we have a standard WAR file we can deploy on Tomcat:

        1. Copy the cfusion.war file into /path/to/tomcat/webapps As indicated above, this will mean your context path will be “cfusion” unless you rename the WAR file while copying it.
        2. Wait a few seconds for Tomcat to auto-deploy the WAR file
        3. Browse to http://localhost:8080/cfusion to complete the installation process for the WAR.
        4. Note that you only have to go through the 12-step program above to generate the WAR once, unless you want to change the installation options. So when you need another instance of ColdFusion on Tomcat, just copy the WAR file over again and give it a different name (and hence a different context path) from any other instances.

          If this matters to you, please be aware that for some reason ColdFusion isn’t officially supported on Tomcat. Why is a bit of a mystery since Tomcat is the servlet container used in JBoss, and in my experience ColdFusion runs just fine on Tomcat. I only bring it up if you’re in an environment where official support matters.

          Why Do This?

          You now have Tomcat running and can easily develop and test on Open BlueDragon, Railo, or Adobe ColdFusion. To me that’s reason enough to use a development setup such as this. Also based on my experience helping people get this type of environment set up, it really does start to open up people’s eyes to what’s really going on under the hood with ColdFusion. Yes, if you do the multi-instance installation of ColdFusion you do get some server management features you don’t get otherwise, but based on how I’m using ColdFusion these days, I simply don’t need those features, particularly on development.

          What I do need, on the other hand, is the ability to develop on both ColdFusion 8 and (increasingly) Open BlueDragon, so rather than trying to shoehorn OpenBD into the ColdFusion/JRun environment, I prefer to use a standard Java servlet container such as Tomcat and put all the CFML engines and instances I need on Tomcat.

          Next Steps

          You’re probably already wondering how to get things to run “for real,” meaning eliminating the port number and context path for your users. This can be done several different ways, so I’ll cover some options in future blog posts. In the mean time, check out Dave’s blog posts (links above) for some info on setting things up with Apache and mod_jk, which is one way to go. You can also change the port Tomcat runs on, or proxy from Apache out to Tomcat for CFML sites, so there’s no shortage of ways to set up more or less any configuration you want.

Matt has provided excellent instructions on how to install on Tomcat openbd and Railo as well as Adobe’s CF, all within the same developer build

This entry was posted in General and tagged , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s