common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,
${catalina.home}/railo,${catalina.home}/railo/*.jar
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:
${catalina.home}/railo,${catalina.home}/railo/*.jar
<servlet>
<servlet-name>RailoCFMLServlet</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-INF/railo</param-value>
<description>Configuration directory</description>
</init-param>
<!-- init-param>
<param-name>railo-server-root</param-name>
<param-value>.</param-value>
<description>directory where railo root directory is stored</description>
</init-param -->
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>RailoAMFServlet</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>
<servlet>
<servlet-name>RailoFileServlet</servlet-name>
<description>File Servlet for simple files</description>
<servlet-class>railo.loader.servlet.FileServlet</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
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:
<servlet-name>RailoCFMLServlet</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-INF/railo</param-value>
<description>Configuration directory</description>
</init-param>
<!-- init-param>
<param-name>railo-server-root</param-name>
<param-value>.</param-value>
<description>directory where railo root directory is stored</description>
</init-param -->
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>RailoAMFServlet</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>
<servlet>
<servlet-name>RailoFileServlet</servlet-name>
<description>File Servlet for simple files</description>
<servlet-class>railo.loader.servlet.FileServlet</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>RailoCFMLServlet</servlet-name>
<url-pattern>*.cfm</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoCFMLServlet</servlet-name>
<url-pattern>*.cfml</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoCFMLServlet</servlet-name>
<url-pattern>*.cfc</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoAMFServlet</servlet-name>
<url-pattern>/flashservices/gateway/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<!-- could be RailoFileServlet -->
<servlet-name>default</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
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:
<servlet-name>RailoCFMLServlet</servlet-name>
<url-pattern>*.cfm</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoCFMLServlet</servlet-name>
<url-pattern>*.cfml</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoCFMLServlet</servlet-name>
<url-pattern>*.cfc</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoAMFServlet</servlet-name>
<url-pattern>/flashservices/gateway/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<!-- could be RailoFileServlet -->
<servlet-name>default</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
sh startup.sh
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 shutdown.sh 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 127.0.0.1.
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>
<Host name="web2.local" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="/Users/yourname/Documents/sites/web2.local/www"/>
</Host>
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 127.0.0.1) and then add the following to Tomcat's server.xml file:
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="/Users/yourname/Documents/sites/web1.local/www"/>
</Host>
<Host name="web2.local" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="/Users/yourname/Documents/sites/web2.local/www"/>
</Host>
<Host name="tomcat.examples" appBase="default"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
</Host>
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).unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
</Host>

46 responses so far ↓
1 Shimju David // May 12, 2009 at 1:06 AM
My entry on server.xml are
<Host name="web1.local" appBase="webapps" unpackWARs="true" autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="c:\inetpub\wwwroot\web1.local"/>
</Host>
<Host name="web2.local" appBase="webapps" unpackWARs="true" autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false">
<Context path="" docBase="c:\inetpub\wwwroot\web2.local"/>
</Host>
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
message
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
3 Jamie Krug // May 12, 2009 at 5:53 AM
http://docs.google.com/Doc?docid=dchcmx7_13dbm8xmgn&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
5 Sean Corfield // May 12, 2009 at 9:13 AM
@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 -www.getrailo.com/index.cfm/services/support/
b) free support from the community - www.getrailo.org/index.cfm/community/mailing-list/
6 Sami Hoda // May 12, 2009 at 10:09 AM
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
10 Brian OConnor // May 29, 2009 at 9:03 AM
11 Shimju David // May 30, 2009 at 1:15 PM
12 Tom Chiverton // Jun 4, 2009 at 9:46 AM
<servlet>
<servlet-name>RailoAMFServlet</servlet-name>
<description>AMF servlet for flash remoting</description>
<servlet-class>railo.loader.servlet.AMFServlet</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<!-- MessageBroker Servlet -->
<servlet>
<servlet-name>RailoMessageBrokerServlet</servlet-name>
<display-name>RailoMessageBrokerServlet</display-name>
<servlet-class>flex.messaging.MessageBrokerServlet</servlet-class>
<init-param>
<param-name>services.configuration.file</param-name>
<param-value>/WEB-INF/flex/services-config.xml</param-value>
</init-param>
</servlet>
and
<servlet-mapping>
<servlet-name>RailoAMFServlet</servlet-name>
<url-pattern>/openamf/gateway/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoMessageBrokerServlet</servlet-name>
<url-pattern>/flex2gateway/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoMessageBrokerServlet</servlet-name>
<url-pattern>/flashservices/gateway/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>RailoMessageBrokerServlet</servlet-name>
<url-pattern>/messagebroker/*</url-pattern>
</servlet-mapping>
13 George Webster // Jun 19, 2009 at 8:03 PM
Followed your blog and flawlessly deployed two railo apps side-by-side.
One additional note:
I added the MessageBrokerServlet definitions per:
http://groups.google.com/group/railo/browse_thread/thread/1681fc25f23b3de3/d60b66a7ee9e7af7?lnk=gst&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
Full details are in https://jira.jboss.org/jira/browse/RAILO-400 including the per-webroot web.xml
15 Sean Corfield // Sep 1, 2009 at 10:13 AM
16 George Webster // Sep 1, 2009 at 10:32 AM
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
18 David // Sep 30, 2009 at 12:12 AM
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:
home/resources/tc_#/conf/
home/resources/tc_#/webapps/
and where they should be:
mydir/webroot/
My Catalina.Props file contains:
common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,/home/resources/tc_3/railo,/home/resources/tc_3/railo/*.jar
My Server.xml Vhost:
<Host name="sbiwd5.kattare.com" unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false" appBase="webapps">
<Context path="" docBase="/home/sites/spectrafluidics2_com" />
<Alias>www.sbiwd5.kattare.com</Alias>
</Host>
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?
Thanks,
David
19 Hatem Jaber // Oct 16, 2009 at 6:51 AM
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.
Thanks,
Hatem
20 Sean Corfield // Oct 16, 2009 at 1:26 PM
21 Mark // Oct 21, 2009 at 1:20 AM
22 Sean Corfield // Oct 21, 2009 at 8:30 AM
23 Jamie Krug // Oct 21, 2009 at 8:56 AM
24 Sean Corfield // Oct 21, 2009 at 10:14 AM
25 Mark // Oct 28, 2009 at 8:50 AM
26 Peter Bell // Oct 28, 2009 at 1:30 PM
http://corfield.org/blog/index.cfm/do/blog.entry/entry/Railo_for_Dummies_Part_III
you need to chmod to make the shell scripts executable:
chmod +x *.sh
27 Andrew Myers // Nov 8, 2009 at 6:18 PM
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 "refresh" all the jars those ones have access to?
Best regards,
Andrew.
28 Sean Corfield // Nov 8, 2009 at 6:24 PM
29 Kevin Pepperman // Jan 18, 2010 at 11:08 PM
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:
<param-value>{web-root-directory}/WEB-INF/railo</param-value>
30 David // Mar 2, 2010 at 2:13 PM
31 Anang A Phatak // Mar 12, 2010 at 8:20 AM
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
http://www.getrailo.org/index.cfm/community/
33 snake // Mar 17, 2010 at 3:36 PM
34 Sean Corfield // Mar 19, 2010 at 5:06 PM
35 snake // Mar 20, 2010 at 1:11 PM
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
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
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
39 Sean Corfield // Aug 5, 2010 at 11:49 PM
40 David Long // Sep 16, 2010 at 6:24 AM
41 Sean Corfield // Sep 18, 2010 at 5:23 PM
42 David Long // Sep 22, 2010 at 2:09 PM
43 Sean Corfield // Oct 3, 2010 at 7:46 PM
44 Howard Fore // Feb 19, 2011 at 9:03 PM
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
context:
delegate: false
repositories:
----------> Parent Classloader:
org.apache.catalina.loader.StandardClassLoader@1a85d38
railo.loader.servlet.CFMLServlet
java.lang.ClassNotFoundException: railo.loader.servlet.CFMLServlet
at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1645)
The same error is repeated for each of the servlets we defined. I've confirmed that the common.loader setting in catalina.properties 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
46 Rick Sarvas // Apr 5, 2011 at 9:26 AM
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.
Leave a Comment