Installing Railo on Tomcat - The Windows Edition

Posted by Todd Rafferty on August 27, 2009

This past week I finally managed to migrate my windows dev boxes from Resin to Tomcat. I ran into a few issues, wanted to document them somewhere. This post will pretty much work for 32 or 64 bit Windows, I'll be sure to point out areas where I had problems with one or the other. Keep in mind, I'm not a JEE server expert. I'm very much stumbling around like everyone else is. Yes, I used to rely on simplified single web installers. No more! If I can do this, so can you.

Great resources to read ahead of time as some of these instructions will sound familiar.

A little bit of a background. I'm comfortable with Windows & CentOS. I run Windows as my development environment and I use CentOS as my production server. That's just how I roll. Jamie & Sean's instructions are written for Ubuntu and OSX respectively and since I'm familiar with CentOS / command line crap, I figured I'd ease the burden and translate for Windows users.

Preamble:

Before we get started, let's open our hosts file ( c:\Windows\System32\drivers\etc\hosts ) - Vista users, it is there. Windows will block you, so use a real editor like notepad++ or something. So, the line that reads:

127.0.0.1    localhost

Add any web host name you want to end of that.

127.0.0.1    localhost testhost1 testhost2

I'm going to refer to testhost1 & testhost2 in this post. You can call your hosts anything you want. I'm going to be setting up 2 virtual hosts in apache / tomcat to refer to these hosts. I'm doing this because I actually got confused as to what I was supposed to do setting up multiple hosts via Tomcat/Apache reverse-proxy.

My paths look like:
c:\dev\Tomcat6\
c:\dev\apache\2.2.3\
c:\dev\website\testhost1
c:\dev\website\testhost2

When you're creating your folder paths and where you want to install things, do yourself a favor... keep it simple. Tomcat doesn't appear to like spaces or periods in path/filenames on Windows for some reason. Tomcat never goes into my apache\2.2.3 directory, so I'm less concerned about that directory naming.

Enough Preambling! Let's get started:

Download JDK ( JDK 6 Update 16 as of this writing ) and install the JDK.
1. Please pay attention to whether you want 32 or 64 bit.
2. For the purpose of this tutorial, I chose to install my JDK to C:\Dev\Java\jdk1.6.0_16
Download Tomcat. I just chose the simple Windows Service Installer.
1. I installed Tomcat to: C:\Dev\Tomcat6 <-- Please note, it's not "Tomcat 6.0" - Whenever possible, with Tomcat on Windows, please remove extra spaces and periods. I'll explain later.
2. Just run through the installer for both 32 & 64 bit windows. Don't start it up when it's finished.
3. 64 bit windows has an extra step. If you started Tomcat, you'll notice that it won't work and you'll probably get a complaint about how it's not a 64 bit app. Go to the Tomcat SVN and grab both tomcat6.exe and tomcat6w.exe and overwrite your existing (In my installation, that was found C:\Dev\Tomcat6\bin ).
If you're done with the above and you've pointed Tomcat at the right JRE ( Mine is: C:\Dev\Java\jdk1.6.0_16\jre ) - Go ahead and start up Tomcat. Verify that it is working at http://localhost:8080/
At this point, you need to decide how you want to install Railo. Railo can be downloaded here.
1. WAR style: You'll want to download the railo-{version}.war ( as of this writing: railo-3.1.1.000.war )
2. JAR style: You'll want to download railo-{version}.jars.{zip or tarball} ( as of this writing: railo-3.1.1.000.jars.zip )

War Installation:

If you have Tomcat running, leave it running.
Download the railo-3.1.1.000.war - rename this to railo.war
Again, 2 ways to install this:
1. Navigate via browser to http://localhost:8080/manager/html ( admin / password is default username / password for Tomcat ).
  1. Scroll down to "WAR file to deploy" and select railo.war and deploy it.
2. Navgiate via Windows Explore to your Tomcat's webapp directory ( my path was: C:\Dev\Tomcat6\webapps )
  1. Drop the .war file and watch it magically explode before your very eyes.
  2. GIVE THIS STEP SOME TIME - Go get a coffee or something. I found that I was removing the .war file TOO SOON. Because of this, I found that I'd prefer to do this via Tomcat's manager because I'm not patient enough. :)
  3. (Corrected by Sean Corfield) Update: You can not remove the railo.war file when the server is running. If you do, Tomcat will take that you want to uninstall the app. So, after you're 100% sure the war explosion is done and you want the railo.war file gone -- shut down Tomcat, remove the .war file, then start it back up again.
http://localhost:8080/railo should now be working for you.

The Common Class Installation Method:

This is where I start to diverge from typical Tomcat installation and rely on the more "senior" guys I mentioned above in my hyperlinks. I'm going to be following Jamie Krug / Sean Corfield's installation guides in particular. This will make Railo a global thing on the Tomcat server. So, if you're wanting to setup CF8, CF9 and OpenBD and such, you're better off sticking with the War installation above. Otherwise, if you know that you'll only be developing with Railo (as you should, like me), then you'll want to follow this route because this route will save you from having to explode a war file for each site you're setting up. If you don't care about the disk space, then go ahead and stay with the war file installation.

If you have Tomcat running, shut it down.
Download railo-3.1.1.000.jars.zip and extract them wherever you feel comfortable. I put mine here: C:\Dev\Tomcat6\railo
Go to your Tomcat's conf directory and open up catalina.properties
1. Change common.loader from: common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar
2. To: common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,${catalina.home}/railo/*.jar
3. If you extracted your jar files elsewhere, then instead of using ,${catalina.home}/railo/*.jar - you would point to ,{your path to your railo jar files}
Save & close catalina.properties
Open up web.xml - This is probably the most lenghty blob of xml we're going to be handling, so... bear with me (us? I got this from Sean / Jamie - I prefer Sean's naming style). Look for the <servlet> section and paste:

<servlet>
    <servlet-name>GlobalCFMLServlet</servlet-name>
    <description>CFML runtime Engine</description>
    <servlet-class>railo.loader.servlet.CFMLServlet</servlet-class>
    <init-param>
        <param-name>configuration</param-name>
        <param-value>{web-root-directory}/WEB-INF/railo/</param-value>
        <description>Configuraton directory</description>
    </init-param>    
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet>
    <servlet-name>GlobalAMFServlet</servlet-name>
    <description>AMF Servlet for flash remoting</description>
    <servlet-class>railo.loader.servlet.AMFServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>

Got it? :( There's more! :( Go to <servlet-mapping> section and paste:

<servlet-mapping>
    <servlet-name>GlobalCFMLServlet</servlet-name>
    <url-pattern>*.cfm</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>GlobalCFMLServlet</servlet-name>
    <url-pattern>/index.cfm/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>GlobalCFMLServlet</servlet-name>
    <url-pattern>*.cfml</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>GlobalCFMLServlet</servlet-name>
    <url-pattern>*.cfc</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>GlobalAMFServlet</servlet-name>
    <url-pattern>/flashservices/gateway/*</url-pattern>
</servlet-mapping>

But, wait! There's more! Find the <welcome-file-list> section and paste: <welcome-file>index.cfm</welcome-file> ( Who the crap uses .cfml extension? )
By now, you're wondering why the hell the numbers on my ordered list are out of sync. That's because TinyMCE is stripping the 'start' attribute from my <ol> :P
We're done with the web.xml - save and close it. Next up hosts!
Open up server.xml - for this, I'm going to be setting up my server.xml with the testhost1 and testhost2 examples I mentioned above. All my domains are going to be hosted c;/dev/websites/{domain}. Look for the <Host> section of server.xml and paste:

<Host name="testhost1" appBase="webapps" unpackWARs="true" autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false">>
	<Context path="" docBase="C:/Dev/websites/testhost1" />
</Host>
<Host name="testhost2" appBase="webapps" unpackWARs="true" autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false">>
	<Context path="" docBase="C:/Dev/websites/testhost2" />
</Host>

At this point, go ahead and create an index.cfm in each host directory with the following code: <cfoutput>#now()# - #cgi.http_host#</cfoutput>
Now, at this point, you're probably itching to start up tomcat and test this. Don't! Don't ask me why, but before you do.. please open up all the xml files in conf directory and line 1 should be: <?xml version='1.0' encoding='utf-8'?> -- Don't ask why either, just do it and save it. All of the XML Files: server.xml, web.xml, tomcat-users.xml.
Now we can test our Tomcat hosts. Start up tomcat in the services panel and test away. http://testhost1:8080/index.cfm & http://testhost2:8080/index.cfm
Should work.

At this point, if you're happy with everything, you can technically stop. You don't need apache. If you're annoyed by the hostname:8080 in the browser every time, you can open up server.xml and do a search for port="8080" and change that to port="80" and close/save/restart Tomcat and you're done.

I'm used to Apache. I prefer Apache's mod_rewrite. You can certainly do without it. I'm told urlrewrite servlet mapping thing works fine. If you're interested in the Apache vhost setup, then continue on. Otherwise, you're done! Enjoy! If something isn't working, drop a line.

The Apache "Stuff"

I'm running Vista 64 running Apache 32 which reverse proxies to a 64 bit Tomcat. Why? Because while there is an apache version that is compiled for 64 bit, it's not from Apache ( to my knowledge ). So, if you plan on using Apache 64 bit, you can... shouldn't be anything different than what I'm suggesting. This isn't a tutorial on how to get apache up and running as I'm assuming you already know that because Apache rocks and you use it already! There's plenty of tutorials out there already on Apache.

Open up httpd.conf in notepad++ (or whatever) and do a search for "#LoadModule proxy_module modules/mod_proxy.so" - uncomment this by removing the # in front of the line.
Uncomment "#LoadModule proxy_ajp_module modules/mod_proxy_ajp.so"
Uncomment "#LoadModule rewrite_module modules/mod_rewrite.so"
Save and close.
Open your httpd-vhost.conf file - using the testhost1 and testhost2 example, it should look like:

<VirtualHost *:80>
    ServerName testhost1
    DocumentRoot "C:\Dev\websites\testhost1"
    DirectoryIndex index.html
    ErrorLog "logs/testhost1-error.log"
    CustomLog "logs/testhost1-access.log" common
	
    <Proxy *>
	Order deny,allow
	Allow from all
    </Proxy>

    ProxyPreserveHost On
    ProxyPass / ajp://testhost1:8009/
    ProxyPassReverse / ajp://testhost1:8009/

    RewriteEngine On
    RewriteRule ^/(.*\.cf[cm]/?.*)$ ajp://%{HTTP_HOST}:8009/$1 [P]
</VirtualHost>
<VirtualHost *:80>
    ServerName testhost2
    DocumentRoot "C:\Dev\websites\testhost2"
    DirectoryIndex index.html
    ErrorLog "logs/testhost2-error.log"
    CustomLog "logs/testhost2-access.log" common
	
    <Proxy *>
	Order deny,allow
	Allow from all
    </Proxy>

    ProxyPreserveHost On
    ProxyPass / ajp://testhost2:8009/
    ProxyPassReverse / ajp://testhost2:8009/

    RewriteEngine On
    RewriteRule ^/(.*\.cf[cm]/?.*)$ ajp://%{HTTP_HOST}:8009/$1 [P]
</VirtualHost>

Save & Close. Restart Apache. http://testhost1/ & http://testhost2/ should just now be working. You can do the additional rewriting in the <VirtualHost> sections or use your .htaccess file as normal.

Aftermath, some additional notes

I mentioned above that everything should be up and running smoothly. I ran into a weird issue with Tomcat 64 / Vista 64. If my directories had spaces or periods in the foldernames, for whatever reason, Railo's WEB-INF directories were not where they were supposed to be. So, do yourself a favor, keep the directory naming as simple as possible.

Hope this helps. Drop a line with questions if you have any.

Update:

Doug Boude asked why I chose Tomcat over Resin. I didn't choose anything over anything really. I got off Resin because I understand it now, I know how to configure it and it's pretty darn simple. I moved to Tomcat to learn Tomcat. So far, I have to say that Resin is nice. The things you can do with the Resin.conf file is pretty fast / easy, such as being able to use regular expression to define the hosts. Resin is definitely the simplier / easier setup out of the two. However, when I talk to JEE guys... they grok Tomcat / Jboss. Resin? What's that? I'm actually working on a volunteer project in which I'm building a CMS for a school and there's another guy volunteering some work as well and he's a java developer and Tomcat is up his alley. So, I'll be switching to meet his needs.

Also, if you want to setup Railo side by side with Open Bluedragon and Adobe ColdFusion, then Tomcat War Installation is the way to go.

Update #2:

If you're looking to eliminate Apache httpd and just use tomcat, but want URL rewriting, you should look into http://tuckey.org/urlrewrite/

Eric Cobb wrote on 08/28/09 11:33 AM

Sweet! This is really going to come in handy!

doug boude wrote on 08/28/09 12:34 PM

Thanks for the step by step, Todd! I wonder...would you happen to know what would change in the steps above if one were using IIS7 rather than Apache? If you don't know off the top of your head I'm sure I can dig that part out of one of the other railo install posts floating around out there.

doug boude wrote on 08/28/09 1:36 PM

Regarding the step about editing the Hosts file on Vista... I ran into some issues doing so on my Vista 64 system that I blogged about. If anybody is using Vista and runs into issues, here's a link to my post:
http://www.dougboude.com/blog/1/2009/07/Hosts-File-Changes-Not-Acknowledged-on-Vista-64.cfm

doug boude wrote on 08/28/09 1:43 PM

geezus, I'm having trouble just trying to download JDK from step 1! There are 5 different choices at that link that are JDK...which one should I grab? The one I thought was the right one didn't mention anything about 32 bit vs 64 bit, so I'm wondering if it WAS the right one. Do we need the JDK? Would the JRE suffice (there was only two choices for that one!). Thanks for your input.

Todd Rafferty wrote on 08/28/09 1:43 PM

Doug, I haven't run into your host issue and I'm running Vista 64. o_O I don't run IIS 7 unfortunately, but I'm sure there's a ton of posts on how to connect Tomcat to IIS7.

Jordan wrote on 08/28/09 2:18 PM

You're installing Railo as a common class, so I personally refer to that installation method as a common class install. =)

Todd Rafferty wrote on 08/28/09 3:25 PM

@Doug: Your two options, either down the JDK or download the JRE. Both will work. I always download the JDK. When you click download, you'll see a Windows (which is 32 bit) or Windows x64 (which is 64 bit) in the drop down. Was in a meeting at work, hope this helped.

Sean Corfield wrote on 08/28/09 6:56 PM

You said "Because of this, I found that I'd prefer to do this via Tomcat's manager because I'm not patient enough"

In my experience, if you remove a WAR file WHILE TOMCAT IS RUNNING, it will undeploy the web application (i.e., remove the exploded directory). It is only safe to remove the WAR file when Tomcat is no longer running.

Todd Rafferty wrote on 08/28/09 7:03 PM

Sean, you're correct. I forgot about that. How can you tell when a war file has been 100% exploded? Not like there's a progress bar somewhere. :) I guess that's why I prefer deploying via tomcat's admin.

I'll fix the direction with your note.

Ryan LeTulle wrote on 08/29/09 9:28 AM

Thanks Todd. You are doing a great job!

Paul Kukiel wrote on 08/29/09 9:32 AM

When you add new Virtual hosts to Tomcat do you need to Stop/Start tomcat like you do with resin ( unless you do a few extra steps ). Also do you need to add extra information for flash remoting and BlazeDS mappings into the web.xml I have been using ( and happy with ) resin but I'm interested in tomcat aswell.

Todd Rafferty wrote on 08/29/09 9:38 AM

@Paul: About BlazeDS mappings: Again, no idea. :(

Regarding restarts, I found this: "Tomcat: you must restart tomcat and apache after adding a new context; Apache doesn't support configuration changes without a restart."

http://tomcat.apache.org/tomcat-3.3-doc/tomcat-apache-howto.html

Todd Rafferty wrote on 08/29/09 9:45 AM

Further information about restarting:
http://www.mail-archive.com/users@tomcat.apache.org/msg58665.html

Or just google it :P
http://www.google.com/search?rlz=1C1GGLS_enUS341US341&sourceid=chrome&ie=UTF-8&q=add+host+without+restart+%2Btomcat

Marty McGee wrote on 09/12/09 11:17 PM

Ah, finally a simple-to-follow, easy-to-understand, and accurate tutorial
post for installing Railo on Tomcat on Apache on Windows XP/Vista/2003/2008.
This configuration worked for me using the following ingredient versions:

Windows XP and Windows Server 2003
JRE 1.6 update 16
Tomcat 6.0 (Windows Service Installer - no periods or spaces in install dir)
Railo 3.1.1-000 Final
Apache Tomcat Connector 1.2.28
Apache 2.2.13

I've tried about 6 other configurations for a working J2EE server using
Railo 3.1.1 on Windows and Apache (not IIS6 or IIS7), including the Resin,
JAR, and WAR configurations available at getrailo.org, Sun's SDK with
Glassfish Server, JBoss, and the Resin Open Source version, and so far
this tutorial's suggestedsetup seems the fastest, most reliable, and
headache-less deployment I've come across.

Thank you Mr. Rafferty for sharing your knowledge with us, and thank you to
the contributors of this post. As you may tell, I'm pretty stoked to have
this super fast configuration working and stable.

- Marty McGee

BDOVPRO wrote on 11/20/09 11:13 AM

Hey i followed the tutorial to the letter and for some reason when I try to load testhost1:8080/index.cfm i get a page with the error:
HTTP Status 404 - Servlet GlobalCFMLServlet is not available

anyone else have this problem?

Todd Rafferty wrote on 11/21/09 8:27 AM

It either means you skipped over the 1st set of XML to paste into the web.xml or you didn't setup the catalina.properties correctly.

RPS wrote on 01/29/10 6:00 AM

you must have forgotten the railo jars or the path to these jars is not correct in the catalina properties. The catalina home refers to the root of tomcat so make sure the path is correct.

jbuda wrote on 06/23/10 9:53 PM

I have been following this exactly, taken me hours to find some problems with the setup i used to have.... hosts file wasnt being picked up by Windows and then my httpd.conf had the old Jrun module... so all .cfm files were being processed by this old connector.... just could not get this tutorial to work.

FInally i went through my conf line by line and deleted everything i knew that didnt belong in it... if it wasnt for bits of old code like that.... following your setup would have taken me minutes!

Thanks for posting this tutorial it has been a great help.

web-rat.com

Installing Railo on Tomcat - The Windows Edition

Preamble:

Enough Preambling! Let's get started:

War Installation:

The Common Class Installation Method:

The Apache "Stuff"

Aftermath, some additional notes

Update:

Update #2:

Leave a comment

Links

Categories

Archives By Month