An Architect's View

CFML, Clojure, Software Design, Frameworks and more...

An Architect's View

Railo on Tomcat - multi-web

May 11, 2009 ·

Today I had a short gap between projects so I finally created a multi-web install of Railo on Tomcat. I'm deeply indebted to Jamie Krug for his Railo JAR install tips and tricks blog post which I used as a starting point for my installation process.Downloading Start with a clean install of Tomcat. I downloaded 6.0.18 and unzipped it into /Developer/tomcat/. Don't start it up yet. For Railo, you'll either need the custom JARs ZIP file or the WAR (which is just a ZIP anyway). The latter makes it a little easier to copy'n'paste the XML fragments you need to add to Tomcat's root web.xml file but I'll show them all below for convenience. Preparation In the Tomcat folder create a railo/ folder and copy in the contents of the unzipped Railo JARs ZIP file (or from the WEB-INF/lib/ folder of the unzipped Railo WAR file). In the Tomcat conf/ folder, edit and find the common.loader class path. We're going to add the Railo JARs to the common class path so that every web application can have Railo CFML pages. The new common.loader definition should look like this (all on one line, no spaces):
Note: embedding Railo directly in Tomcat like this means that you will end up with a generated WEB-INF/ folder in each webroot, containing some Railo files (about 2MB). Unless you're going to use the default web applications that come with Tomcat, this is a good time to empty the Tomcat webapps/ folder. You could create a default/ folder in the Tomcat folder and move everything from webapps/ to default/ - this makes it easy to configure the applications again under a new hostname (I'll show this at the end). Next we must configure the Railo Servlet stuff. In the Tomcat conf/ folder, edit web.xml. This is the master web application configuration for the Tomcat server and any web applications you create will inherit from it. At the end of the servlet section, just before the servlet-mapping section, add the following:
   <description>CFML runtime Engine</description>
<description>Configuration directory</description>
   <!-- init-param>
<description>directory where railo root directory is stored</description>
</init-param -->
   <description>AMF Servlet for flash remoting</description>
   <description>File Servlet for simple files</description>
Note that I have prefixed these Servlets with Railo so that you can still deploy Railo WAR-based web apps without conflict (chops to Jamie Krug for this - he renamed his Servlets to have GLOBAL in front of their names). Next, at the end of the servlet-mapping section, just before the filter section, add the following:
   <!-- could be RailoFileServlet -->
Note that I have used the default Tomcat Servlet for serving files, per my recent Quick Tip (so you need to set listings to true in the default Servlet definition at the top of the file if you want directory listings). Finally, at end of the file, add index.cfm (and index.cfml if you wish) to the list of "welcome files". If you emptied the webapps/ directory above, create an empty folder called ROOT/ in there so that we'll have at least one web application when we start Tomcat. Let's get this party started! We're ready to start Tomcat now. In Terminal, go to the Tomcat bin/ folder and start Tomcat:
In a few seconds, you'll be able to browse to http://localhost:8080/ and see an empty directory listing. How exciting! Browse to http://localhost:8080/railo-context/admin.cfm and you should see the Railo entry page for the Server and Web Administrators. Login to each and set an initial password. At this point, the Server Administrator data is actually stored in {tomcat}/railo/railo-server/ and the Web Administrator data is stored in {tomcat}/webapps/ROOT/WEB-INF/railo/. Settings in the Server Administrator cascade down into all the Web Administrators associated with the Tomcat server - and the Server Administrator can determine what features can be changed in those Web Administrators. You can stop Tomcat now (by switching to the org.apache.catalina.startup.Bootstrap application and selecting Quit from the menu). The script does not reliably shut Tomcat down for a number of web applications. Adding websites The first step is always to add a new domain name for each site to your local hosts file so all those domains resolve to Let's assume you have web1.local and web2.local defined there. Let's also assume that the desired webroots for these sites are ~/Documents/sites/web1.local/www/ and ~/Documents/sites/web2.local/www/. In the Tomcat conf/ folder, edit server.xml and find the Host definition for localhost (around line 126). You can add your new host definitions below that, as follows:
<Host name="web1.local" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">

      <Context path="" docBase="/Users/yourname/Documents/sites/web1.local/www"/>
<Host name="web2.local" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">

      <Context path="" docBase="/Users/yourname/Documents/sites/web2.local/www"/>
Now start Tomcat again and you'll see a WEB-INF/ folder created inside each of those two sites' www/ folders. Browse to http://web1.local/railo-context/admin/web.cfm, set a new password and login. This is the Web Administrator for the web1.local website. Similarly, http://web2.local/railo-context/admin/web.cfm is the Web Administrator for the web2.local website. The Server Administrator accessible from http://web1.local/railo-context/admin/server.cfm is the same, shared Server Administrator under localhost or web2.local. You now have a shared hosting environment on your local computer with each 'account' having its own full administrator console! Those default Tomcat applications Remember we moved those default applications (docs, examples, host-manager, manager, ROOT)? You can easily make them accessible again as a new website. Add tomcat.examples to your hosts file (resolving to and then add the following to Tomcat's server.xml file:
<Host name="tomcat.examples" appBase="default"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">

Note the appBase is a different top-level folder in Tomcat. When you next restart Tomcat, you'll see Railo's files added to the WEB-INF/ in each of those five web applications but you'll be able to browse to http://tomcat.examples/docs for example (and view the Tomcat documentation).

Tags: coldfusion · railo

49 responses

  • 1 Shimju David // May 12, 2009 at 1:06 AM

    Iam on windows and installation went well like you explained. But few issues I face now are:

    My entry on server.xml are
    &lt;Host name=&quot;web1.local&quot; appBase=&quot;webapps&quot; unpackWARs=&quot;true&quot; autoDeploy=&quot;true&quot; xmlValidation=&quot;false&quot; xmlNamespaceAware=&quot;false&quot;&gt;
    &lt;Context path=&quot;&quot; docBase=&quot;c:\inetpub\wwwroot\web1.local&quot;/&gt;
    &lt;Host name=&quot;web2.local&quot; appBase=&quot;webapps&quot; unpackWARs=&quot;true&quot; autoDeploy=&quot;true&quot; xmlValidation=&quot;false&quot; xmlNamespaceAware=&quot;false&quot;&gt;
    &lt;Context path=&quot;&quot; docBase=&quot;c:\inetpub\wwwroot\web2.local&quot;/&gt;

    I can see WEB-INF folder with subfolders like flex, railo and an .htaccess file under these two website folder. But once I access the website http://web1.local:8080/railo-context/admin/server.cfm Iam getting error says below

    HTTP Status 404 -

    type Status report


    description The requested resource () is not available.
    Apache Tomcat/6.0.18

    . Please note that IIS is running with CF8 on port 80 and thats the reason I called the railo webs using 8080 ports.

    Please advice.

  • 2 Tom Chiverton // May 12, 2009 at 2:12 AM

    Ace guide Sean, cheers. Am I correct in thinking you'd then just use a per-virtual host mod_proxy if you needed it to sit behind an existing Apache ?
  • 3 Jamie Krug // May 12, 2009 at 5:53 AM

    Hey, thanks, Sean! I'm also documenting my production VPS (Ubuntu Linux) configuration here:;hl=en

    It's basically just as you've outlined things above, but I have the file system locked down a bit better and auto-run the Tomcat service as an unprivileged user. The is much more secure, but you need to be careful about providing the tomcat user permissions in any directories where Railo needs to write to the file system (e.g., WEB-INF under each Web root, by default). For development environments, it's of course easiest to keep things in a home folder, running as your main/regular user so there are no permissions to worry about.

    I've also implemented your tips for AJP proxying from Apache and hiding/protecting the Railo Admin URLs.
  • 4 Ryan // May 12, 2009 at 8:52 AM

    for this line &quot;In the Tomcat conf/ folder, edit catalina.out and find the common.loader class path.&quot; - should this be
  • 5 Sean Corfield // May 12, 2009 at 9:13 AM

    @Ryan, good catch. Fixed.

    @Jamie, yes, good points re: security - thanx for the link to your doc!

    @Tom, yes, or a wildcard mod_proxy if you don't need per-virtual host specific Apache configuration (i.e., and let Tomcat handle everything).

    @Shimju, a couple of questions: can you hit localhost:8080/railo-context/admin.cfm ? can you put a test.cfm file in web1.local and hit web1.local:8080/test.cfm ? That will show whether it's a problem with your basic Tomcat / Railo setup or just the Host/Context.

    Remember, your best bet for support is either:

    a) a paid support program from Railo

    b) free support from the community -
  • 6 Sami Hoda // May 12, 2009 at 10:09 AM

    Wow. Thanks Jamie and Sean. This is really interesting stuff. I think I'll try out the combo of Ubuntu, Apache, Tomcat, and Railo...
  • 7 Shimju David // May 12, 2009 at 3:50 PM


    Now after system restart, everything seems working perfectly. Both web1.local:8080/ and web2.local:8080/ are working fine including railo context. I can able to hit localhost:8080/railo-context/admin.cfm earlier also.
    Thanks a lot Sean for this nice article. More I play on Railo, more it seems interesting. I bet Railo can bring more opensource applications into our CFML world.
  • 8 Shimju David // May 17, 2009 at 3:33 AM

    Tomcat doesn't do URL rewriting, so I think of replacing it with RESIN. Can we able to a create a multi-web install of Railo on RESIN?
  • 9 Sean Corfield // May 17, 2009 at 4:14 AM

    @Shimju, yes, this is possible with Resin as well. I'm not yet familiar enough with Resin to post instructions but I'll make sure we post them soon (ultimately, all these install how-to posts will become part of the core documentation on the Railo site).
  • 10 Brian OConnor // May 29, 2009 at 9:03 AM

    @Shimju, It is very easy to add URL rewriting to Tomcat, see
  • 11 Shimju David // May 30, 2009 at 1:15 PM

    Thanks Brian for that URL.
  • 12 Tom Chiverton // Jun 4, 2009 at 9:46 AM

    Just a note that for Railo 3.1 the correct servlet and servlet mappings for AMF support are

    &lt;description&gt;AMF servlet for flash remoting&lt;/description&gt;
    &lt;!-- MessageBroker Servlet --&gt;

  • 13 George Webster // Jun 19, 2009 at 8:03 PM

    Thanks Sean, simply brilliant!

    Followed your blog and flawlessly deployed two railo apps side-by-side.

    One additional note:

    I added the MessageBrokerServlet definitions per:;q=blazeds#d60b66a7ee9e7af7

    Only I followed your lead and prefixed them as RailoMessageBrokerServlet and both apps now server data to flex via blazeds.

    Thanks Again.

  • 14 Tom Chiverton // Sep 1, 2009 at 3:20 AM

    One minor point is that this won't work for Flex Remoting, as you need to make a unique RailoMessageBrokerServlet for each web root.

    Full details are in including the per-webroot web.xml
  • 15 Sean Corfield // Sep 1, 2009 at 10:13 AM

    @Tom, thanx for that detail - I haven't done much with Flex Remoting on Railo yet.
  • 16 George Webster // Sep 1, 2009 at 10:32 AM

    @Tom, Right! I realized this later. I think only the servletId needs to be unique, however I made a small web-app declaration in each WEB-INF/web.xml file per railo instance i needed blazeds for.

    The declaration is basically the same only for each with only a simple servlet and servlet-mapping declared in each web.xml

    I think only the ServletId needs to be unique, but it doesn't hurt to namespace all of them.
  • 17 Nick Harvey // Sep 1, 2009 at 7:14 PM

    Thanks Sean, both this tutorial and Jamie's one have been incredibly helpful with getting my noob head around Tomcat and Railo. One problem that I hit with Tomcat6 is that I kept getting a org.apache.tomcat.util.digester.Digester fatalError showing up in my logs every time I added the railo directories to my server classpath. The issue turns out to be an incorrect encoding in the tomcat-users.xml file in /conf (tomcat bug: Anyway, changing that to ISO-8859-1 solved that and Tomcat is now happily serving CFM's! Just in case that's useful for others.
  • 18 David // Sep 30, 2009 at 12:12 AM

    AWESOME! I can't tell you how many countless hours i've been trying to get this set up on my Slackware box. My server guys have set up tomcat instances under home/resources/tc_1 , tc_2, etc as means to balance the load for some sites that require more attention than others. Meanwhile, all the tomcat instances reference back to a generic tomcat/lib which is the catalina_home.

    Sorry for the introduction but i felt it necessary if i'm to figure out my issue as follows:

    I followed the above perfectly and all seems to finally work. However, i have copies of web-inf in the following directories:
    and where they should be:

    My Catalina.Props file contains:

    My Server.xml Vhost:
    &lt;Host name=&quot;; unpackWARs=&quot;true&quot; autoDeploy=&quot;true&quot;
    xmlValidation=&quot;false&quot; xmlNamespaceAware=&quot;false&quot; appBase=&quot;webapps&quot;&gt;
    &lt;Context path=&quot;&quot; docBase=&quot;/home/sites/spectrafluidics2_com&quot; /&gt;

    Again, thanks so much for a great tutorial! Have any suggestions for this problem? I'm also going to try Jamie Krug's SES for Railo, Tomcat, and Mura CMS. Any suggestions on that one?


  • 19 Hatem Jaber // Oct 16, 2009 at 6:51 AM

    Just an FYI, not sure why I had to do this, but wanted to document it here for future reference. I followed the entire setup step by step, but at the end the localhost:8080 and the localhost:8080/railo-context/admin.cfm did not load. After I checked the log files (thanks jamie krug) it lead me to the solution for the error that i recieved in my tomcat-users.xml file. The original line that was causing the problem was &lt;?xml version=&quot;1.0&quot; encoding=&quot;cp1252&quot;?&gt; and the fixed line &lt;?xml version=&quot;1.0&quot; encoding=&quot;ISO-8859-1&quot;?&gt;

    I'm not sure if i should change this to UTF-8, but i looked at web.xml and that's what it had, so i wanted to keep them consistent. Is there a difference and should it be UTF-8? That would be good to know.


  • 20 Sean Corfield // Oct 16, 2009 at 1:26 PM

    @Hatem, I've a few people run into that. No idea why some Tomcat installs have that broken encoding (unfortunately nothing we at Railo can do about it - other than add a note about it to any Railo-on-Tomcat installation guide).
  • 21 Mark // Oct 21, 2009 at 1:20 AM

    Hi Sean great post I have used this to setup my tomcat/railo installation, but have one question that i hope you or one of the guys here can help me with, I have multiple apps in the webapps directory of tomcat and when I start tomcat they all get the web-inf add on for railo, I was wondering if there was any way I could exempt these directories from this?
  • 22 Sean Corfield // Oct 21, 2009 at 8:30 AM

    @Mark, my understanding is that once you integrate Railo's JAR files into Tomcat, it treats all web applications equally and there's no way to turn it off for specific web applications. I've not seen anyone post a way to do that - and it would certainly be useful in some situations.
  • 23 Jamie Krug // Oct 21, 2009 at 8:56 AM

    @Mark, @Sean, I know Gert posted an interesting theory on the Railo Google list recently. I think the basic idea is to place all Railo jars *except railo.jar* in a Tomcat classpath. Then, just create a WEB-INF with the railo.jar for each app that requires Railo. Sounds good in theory anyway, but I don't have time to tinker right now :) I'd also imagine that this would mean separate Railo Server Admins for each app, which may not be desirable, but you'd basically get the equivalent of full-blown Railo WARs for each app while sharing most the lib and conserving server resources.
  • 24 Sean Corfield // Oct 21, 2009 at 10:14 AM

    @Jamie, interesting. That would remove the main benefit (for me) of auto-deployment tho' and the centralized server administration that I rely on.
  • 25 Mark // Oct 28, 2009 at 8:50 AM

    Hi Sean have a multi-web configuration running fine but have noticved something odd today I have now lost the ability to view debug information when enabled from the aministrator any ideas?
  • 26 Peter Bell // Oct 28, 2009 at 1:30 PM

    A detail, but as mentioned in your previous guide:

    you need to chmod to make the shell scripts executable:

    chmod +x *.sh
  • 27 Andrew Myers // Nov 8, 2009 at 6:18 PM

    Hi Sean,

    Thanks for a great tutorial.

    I had to include the oracle jar but didn't discover this until after following your instructions.

    When I put this into {catalina.home}/railo it doesn't seem to be accessible by my subsites.

    Is there any way to &quot;refresh&quot; all the jars those ones have access to?

    Best regards,
  • 28 Sean Corfield // Nov 8, 2009 at 6:24 PM

    @Andrew, if you want the Oracle driver accessible by all Tomcat sites, put it in {catalina.home}/lib/ (and restart Tomcat).
  • 29 Kevin Pepperman // Jan 18, 2010 at 11:08 PM

    Using the RAILO war on Tomcat/6.0.20 I was seeing this Warning on startup:

    javax.servlet.ServletException: static path [/WEB-INF/railo/] for servlet init param [railo-web-directory] is not allowed, path must use a web-context specific placeholder.

    Using the context variable like Resin app-default.xml uses Seems to fix the warning:

  • 30 David // Mar 2, 2010 at 2:13 PM

    @Kevin... thanks for update! that totally helped get rid of that error for me too!
  • 31 Anang A Phatak // Mar 12, 2010 at 8:20 AM

    What is a good place for posing questions to the Railo Community.
    I was load-testing a setup similar to the one described here ...
    I am sending in 10 concurrent requests for 100 iterations. I can see that railo handles 1 request at a time (others wait till previous request is finished), while Adobe CF-8 is handling multiple request (5 users wait while 5 are finished).

    However, each individial request is faster in Railo than CF-8.

    The application being tested is a webservice and is exactly the same.

    I would like someone to ponder over this with me :)
  • 32 Sean Corfield // Mar 12, 2010 at 2:39 PM

    @Anang, the Railo mailing list is the place for questions:
  • 33 snake // Mar 17, 2010 at 3:36 PM

    Hey Sean, I already have Apache on the server so tomcat wont be able to listen on port 80, do you have any details on how to use Apache instead of tomcat as the webserver.
  • 34 Sean Corfield // Mar 19, 2010 at 5:06 PM

    @snake, sure, I cover that in the Railo for Dummies blog post series (March 2009).
  • 35 snake // Mar 20, 2010 at 1:11 PM

    well that turned out to be a lot easier than I was expecting, once you realise you have to use proxies. I do now appreciate the magic jrun does for you now though.
    I notice however that I do not have a railo application showing in the tomcat manager, is this because you have used the default tomcat servlet, and is there any benefit to this rather than running it as a separate application.
  • 36 ziggy // Apr 7, 2010 at 4:51 AM

    When updating Railo, do we have to go to every server instance and update every one separately?

    Why can't everything be kept in one place for Railo so the same files are not duplicated everywhere?
  • 37 Sean Corfield // Apr 11, 2010 at 4:18 PM

    @ziggy, if you follow the multi-web setup outlined here, there is just one set of Railo server files and one Server Administrator. When you update it, all web contexts will reflect that update.

    You only have to update multiple server instances if you installed Railo as a separate WAR for each web context.
  • 38 Brad // Aug 5, 2010 at 7:59 PM

    So quick question. I have Tomcat setup with multiple instances as outlined in your post, however I need to be able to access the sites from the 'outside'. In other words only displays the root site. Thanks!
  • 39 Sean Corfield // Aug 5, 2010 at 11:49 PM

    @Brad, any domains defined via Host directives in server.xml will be accessible externally.
  • 40 David Long // Sep 16, 2010 at 6:24 AM

    @sean I have railo successfully installed on Tomcat, but I am not sure how to shut it down like you say to do (by switching to the org.apache.catalina.startup.Bootstrap application and selecting Quit from the menu). I appear to have an application (looks like Railo) that breaks the from shutting down all the way. Could you give step-by-step instruction on how to follow the method above?
  • 41 Sean Corfield // Sep 18, 2010 at 5:23 PM

    @David, don't use the script. Use cmd-tab to switch the to the org.apache.catalina.startup.Bootstrap application - the icon is a coffee cup on a couple of sheets of paper with a pen next to the cup - and then select Quit from the menu (the menu name is org.apache.catalina.startup.Bootstrap - because that's the application name). It's just like any other Mac application (except it has no open windows) so you quit it exactly the same way you quit any running application.
  • 42 David Long // Sep 22, 2010 at 2:09 PM

    @sean How about on Linux or Windows? I tried using alt-tab but there is no coffee cup icon.
  • 43 Sean Corfield // Oct 3, 2010 at 7:46 PM

    @David, no idea about Windows. On Linux, you can just 'kill' the process. Remember, I really don't use GUIs much - just the command line.
  • 44 Howard Fore // Feb 19, 2011 at 9:03 PM

    Sean, I'm trying to follow your instructions here. However I keep getting the following error:

    Feb 19, 2011 11:39:42 PM org.apache.catalina.core.StandardEngine start
    INFO: Starting Servlet Engine: Apache Tomcat/6.0.28
    Feb 19, 2011 11:39:42 PM org.apache.catalina.core.ApplicationContext log
    INFO: Marking servlet RailoCFMLServlet as unavailable
    Feb 19, 2011 11:39:42 PM org.apache.catalina.core.ApplicationContext log
    SEVERE: Error loading WebappClassLoader
    delegate: false
    ----------> Parent Classloader:
    java.lang.ClassNotFoundException: railo.loader.servlet.CFMLServlet
       at org.apache.catalina.loader.WebappClassLoader.loadClass(

    The same error is repeated for each of the servlets we defined. I've confirmed that the common.loader setting in is set to include ${catalina_base}/railo,${catalina_base}/railo/*.jar.

    It looks to me like the JAR files aren't getting picked up in the classpath. Any ideas?
  • 45 Sean Corfield // Feb 20, 2011 at 9:09 AM

    @Howard, all I can say is you've either missed a step or done one of the steps wrong. First off, I'd recommend using the integrated installers now instead of a manual install. Since Railo 3.2 was released, those are the standard. Second, I'd recommend joining the Railo list and asking there since you can post more code / config and lots of folks are there to help. Blogs are not a good way to get tech support :)
  • 46 Rick Sarvas // Apr 5, 2011 at 9:26 AM

    Thanks for the info, this worked for me as a localhost test instance.

    Win32 system (Windows 7)
    Java 1.6.0_24
    Tomcat 7.0.11
    Railo 3.2.2

    Other WARs on the same Tomcat instance seem to still be working fine as well.
  • 47 Ron Stewart // Feb 5, 2013 at 5:01 AM

    @Sean: First of all, thanks for posting this. Great recipe; I set up one of my Linux boxes as a test server using this approach several months ago and it worked well.

    I bumped into a bit of a head-scratcher yesterday evening updating to the latest version of Tomcat (7.0.35) that I thought I would pass along in the hopes of saving someone else a bit of pain. I've updated to each successive version of Tomcat my renaming the tomcat/default, tomcat/lib, and tomcat/bin folders in the installation folder to include their version numbers and then replacing them with the updated versions from the Tomcat downloads. For example, tomcat/bin becomes tomcat/bin-7.0.34; same sort of thing for the other folders from the Tomcat distribution. This makes it easy to fall back to a previous version if needed.

    Prior to 7.0.35, updating Tomcat has been completely painless. After updating to 7.0.35, none of my contexts would start. Downgrading to 7.0.34 (easily accomplished by swapping the 7.0.34 and 7.0.35 folders) resulted in a functional box again; swap them back and... broken. Looking in the Catalina log, Tomcat was complaining about having two serlvet-mappings called "default" mapped to "/". Perhaps I read the process above too literally in setting up the five servlet-mapping entries in conf/web.xml, but the creation of the fifth mapping using the "default" entry and url-pattern "/" is a duplicate of the default mapping already present in the stock conf/web.xml (it is the first servlet-mapping in the file). Prior to 7.0.35, it never caused any problems but 7.0.35 wouldn't start any of the contexts with the duplicate in place. As I am using the default servlet, it was then a simple matter of commenting out the first of the default servlet-mapping entries and Tomcat was happy again.
  • 48 Gernot // Nov 6, 2013 at 12:52 PM

    @Ron - This is exactly the problem with these instructions in Tomcat versions later than 7.0.35. Rather than commenting out the first default entry, I opted to remove the second one provided here.

    !-- could be RailoFileServlet --
    servlet-name default servlet-name
    url-pattern / url-pattern
  • 49 viuha // May 25, 2014 at 12:24 AM

    In a cloud platform, when provisioning a Virtual Machine, how to deploy railo in a VM with multiple web applications running on top of it.