Railo JARs on JBoss (or Tomcat) - Tips and Tricks
As a follow up to a previous related post, I wanted to share a couple potentially helpful tricks that I've since learned. Everything I document here has been tested with both Railo 3.0.2.004 (current stable) and Railo 3.1.0.012 (current beta), both of which can be downloaded from here, on JBoss Application Server (AS) 4.2.3.GA.
The purpose (as I see it) of a Railo JARs installation is to provide an alternative to using a full-blown Railo WAR for each of your Railo CFML applications. This allows you to define your Railo CFML servlet "globally" in JBoss/Tomcat and then use virtual hosts for multiple CFML apps. Each CFML app is then leveraging the same Railo instance, one copy of the jars and one Railo server admin (but still multiple Web contexts with unique Railo Web Admin for each Web site/context).
Also keep in mind that JBoss AS leverages Tomcat as its Web server, so just about everything here should directly translate. Here are the locations of key configuration files and directories in both JBoss 4.2 and Apache Tomcat 6:
{JBOSS_HOME}/lib/ {JBOSS_HOME}/server/default/lib/
or
{TOMCAT_HOME}/lib/
{JBOSS_HOME}/server/default/deploy/jboss-web.deployer/conf/web.xml
or
{TOMCAT_HOME}/conf/web.xml
{JBOSS_HOME}/server/default/deploy/jboss-web.deployer/server.xml
or
{TOMCAT_HOME}/conf/server.xml
Quick Review of Railo JARs Install on JBoss/Tomcat
I will first give a very brief outline of the steps required to install Railo (jars) on JBoss/Tomcat here. There are, however, some potential problems with this configuration, which I'll outline below, with a solution/workaround for each.
- Download and "install" (simply extract to a directory) JBoss or Tomcat.
- Download the Railo WAR (from here) and extract (unzip) to a temporary location. Note that I'm suggesting the WAR download and not the "jars" download, because the "jars" download is simply the contents of the WAR's WEB-INF/lib folder; plus, we'll need to copy some XML snippets from the Railo WAR's web.xml file.
- Copy the contents of the Railo WAR's WEB-INF/lib folder (a bunch of .jar files) into your JBoss/Tomcat /lib folder.
- Copy from your Railo web.xml file to your JBoss/Tomcat web.xml file each servlet block, each servlet-mapping block and the two welcome-file tags (there is already similar XML for each block in the JBoss/Tomcat web.xml file, so it should be obvious where each piece goes).
- In your JBoss/Tomcat server.xml file, after the last Host entry, add a new entry like the example below, where the appBase attribute is the Web root of a CFML app (also be sure the host name and/or alias is added to your local hosts file).
- Start JBoss/Tomcat and browse to your virtual host on port 8080 (e.g., http://mysite.com:8080/index.cfm). You should see your CFML output.
The following is an example for your JBoss/Tomcat server.xml file. You can also add additional tags and attributes to control log files and much more (see Tomcat docs).
<Alias>www.mysite.com</Alias>
<Context path="" docBase="" />
</Host>
Potential Problems/Inconveniences
The beauty of the above configuration is that Railo handles a bunch of details automatically, but you may or may not like the results.
First, it just feels a little funny to "blend" all of the Railo jars in a main JBoss deployment /lib folder with a bunch of other JBoss related .jar files. I'll show you how to define a specific directory location, so you can keep your Railo jars in their own directory.
When you first hit a CFML page, Railo will create a lot of files and directories for you. A "railo-server" directory structure is created within your JBoss/Tomcat /lib directory and a WEB-INF directory structure is created in the root of each virtual host directory as well as each top-level directory of each virtual host root. These files and directories provide templates and configuration for server-wide settings (Railo Server Admin) and individual Web context (site/virtual host) settings (Railo Web Admins). This may or may not be an issue, but I don't think I want to have all of this in my Subversion repos, nor do I want to deal with svn:ignore settings. I'll also show you how to specify configuration directory locations for both the server admin and the Web context directories.
Finally, if you choose to use this configuration, but also want to deploy a Railo WAR (or two or more), then you'll run into a "Child name 'CFMLServlet' is not unique" error when you try to start JBoss. I'm hoping to have my "global" Railo jars install handle my smaller CFML apps while also deploying a Railo WAR app or two to experiment with some more enterprisey ideas. I'll show you how to make a few minor naming changes in the JBoss web.xml to allow for all of the above.
Custom /lib directory for Railo JARs
Rather than dumping all the Railo JARs on top of the JBoss JARs you can create a railo-{version}/lib path and let JBoss know where to find it. For example, I've created this directory: {JBOSS_HOME}/server/default/deploy/jboss-web.deployer/railo-3.1.0.012/lib
To let JBoss know to load this class path, add a classpath tag in {JBOSS_HOME}/server/default/conf/jboss-service.xml (just after the existing classpath tag, near the top):
Custom Railo Server and/or Web Admin Directories
You can control the location of Railo Server Admin and Railo Web Admin directories by making simple changes to the CFMLServlet servlet definition (in web.xml). Take note of the two param-value definitions in the following example.
<servlet-name>CFMLServlet</servlet-name>
<description>CFML runtime Engine</description>
<servlet-class>railo.loader.servlet.CFMLServlet</servlet-class>
<init-param>
<param-name>configuration</param-name>
<param-value>/etc/railo/web-config/{web-context-hash}</param-value>
<description>Railo Web contexts configuraton directory (where Web admin roots and configuration files will be stored)</description>
</init-param>
<init-param>
<param-name>railo-server-root</param-name>
<param-value>/etc/railo/server-config</param-value>
<description>Railo server configuration directory (where server admin root and configuration files will be stored)</description>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
You'll want to prepare for the above example by creating the /etc/railo/web-config and /etc/railo/server-config directories. Then, a /etc/railo/server-config/railo-server directory will be generated, and a hash-named directory for each Railo Web context will be created (by Railo) beneath /etc/railo/web-config.
Global Railo Servlet Plus Railo WAR Apps
If you'd like to use the configuration described above but also drop a Railo WAR in your JBoss deployment directory (say, to test out a brand new beta version:) you'll need to alter the servlet names in your JBoss/Tomcat web.xml file in both the servlet and servlet-mapping blocks. In the following snippet examples, I've simply prepended "GLOBAL" to make the servlet names unique (different than that used in any Railo WARs you deploy as well).
<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>/etc/railo/web-config/{web-context-hash}</param-value>
<description>Railo Web contexts configuraton directory (where Web admin roots and configuration files will be stored)</description>
</init-param>
<init-param>
<param-name>railo-server-root</param-name>
<param-value>/etc/railo/server-config</param-value>
<description>Railo server configuration directory (where server admin root and configuration files will be stored)</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>
<servlet>
<servlet-name>GLOBALFileServlet</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-name>GLOBALCFMLServlet</servlet-name>
<url-pattern>*.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>
<servlet-mapping>
<servlet-name>GLOBALFileServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
Resources
I did figure a thing or two out on my own, but not without a good deal of direction from key blog posts by Markus Skrabal. After reviewing this post and this post with the help of Google Translate to decipher the German for me, I was on my way. Thanks, Markus!
Finally, a last-minute disclaimer: I'm still pretty much a JEE n00b, so I'm not absolutely certain how much of the above is a good idea or follow best practices, but it does allow me to use one JBoss AS instance to power a bunch of smaller Railo CFML apps (Web contexts) as well as one or more Railo WAR (full-blown JEE) apps, while sharing Railo Server Admins and controlling directory locations as needed.
Comments (19) |
41573 Views
Darius
Very cool. I'm basically making the same "big switch" :) I was using, just about exclusively, Windows/CF (both IIS and Apache) for roughly 8 years. After leaving my last job (about 4 months ago) I switched my development laptop to Ubuntu and VPS hosting to Linux (CentOS). Now I'm moving a lot of things, including my VPS, to Ubuntu/Apache/JBoss/Railo. It is a big switch, but exciting too!
FYI, here's a useful resource for securing a production-ready JBoss on Ubuntu (I'll probably use this as a reference when configuring my new VPS this week):
http://chiralsoftware.com/linux-system-administrat...
Best,
Jamie
07:30:45,400 ERROR [[FileServlet]] Servlet.service() for servlet FileServlet threw exception
java.io.FileNotFoundException: /opt/jboss-test/server/default/deploy/jboss-web.deployer/ROOT.war/WEB-INF/railo/context/admin (Is a directory)
at java.io.FileInputStream.open(Native Method)
at java.io.FileInputStream.<init>(FileInputStream.java:106)
at railo.commons.io.res.type.file.FileResource.getInputStream(FileResource.java:198)
at railo.commons.io.IOUtil.copy(IOUtil.java:153)
at railo.runtime.engine.CFMLEngineImpl.serviceFile(CFMLEngineImpl.java:273)
at railo.loader.servlet.FileServlet.service(FileServlet.java:32)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:803)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:290)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
at org.jboss.web.tomcat.filters.ReplyHeaderFilter.doFilter(ReplyHeaderFilter.java:96)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
at com.intergral.fusionreactor.filter.FusionReactorFilter.G(Unknown Source)
at com.intergral.fusionreactor.filter.FusionReactorFilter.B(Unknown Source)
at com.intergral.fusionreactor.filter.FusionReactorFilter.doFilter(Unknown Source)
at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:235)
at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:206)
at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:230)
at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:175)
at org.jboss.web.tomcat.security.SecurityAssociationValve.invoke(SecurityAssociationValve.java:179)
at org.jboss.web.tomcat.security.JaccContextValve.invoke(JaccContextValve.java:84)
at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:128)
at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:104)
at org.jboss.web.tomcat.service.jca.CachedConnectionValve.invoke(CachedConnectionValve.java:156)
at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:109)
at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:241)
at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:844)
at org.apache.coyote.http11.Http11Protocol$Http11ConnectionHandler.process(Http11Protocol.java:580)
at org.apache.tomcat.util.net.JIoEndpoint$Worker.run(JIoEndpoint.java:447)
at java.lang.Thread.run(Thread.java:619)
Paul G Cormier
WinCorp Software, Inc.
I doubt there's concern for those XML configs being there. It's standard practice for any JEE WAR/EAR app to have a WEB-INF under the root.
I suggest posting your question to the Railo Google Group to get better clarification than I can provide off the top of my head. You may even want to search existing discussions first, as I recall some discussion around this type of stuff.
http://www.getrailo.org/index.cfm/documentation/co...
(note sub-links in left nav too - 3, to date)
You will need to change your appPath to "/" and change the docBase property in the Context to the actual absolute path to your website folder (This was happening on Windows with Railo 3.1 and Tomcat).
In other words:
<Host name="mysite.local" appBase="/">
<Context path="" docBase="C:\myWebSites\mysite.local" />
</Host>
Again, this was on windows and the specific symptom I was having (In win 7 anyway) was after starting Tomcat, it was dropping a WEB-INF folder in EVERY folder under my web directories, which was annoying to say the least given that I use version control :)
Hope this helps someone...I will get around to posting this on my blog sometime soon as well!!
Yes, I have found it important to set your Context docBase to the absolute path of your Web root (same as DocumentRoot in Apache vhost), however, I leave my Host appBase as "webapps" in Tomcat. I believe appBase="/" is stating the root directory on Linux, or the C:\ drive for Win in your example. You may very well have some dirs generated at your C: root, no? :)
So, the Railo jar does indeed generate the WEB-INF dir under each Web app/root under my tomcat/webapps dir, but I delete all the defaults anyway and just leave the ROOT webapp with a test index.html file. I use a Tomcat Host to set a docBase matching each of my Apache vhost's DocumentRoot. This has been working great.
As for generated directories that you don't want under version control, you can just svn ignore all WEB-INF folders if you'd like.
Cheers!
Yeah good call...it actually was dumping a WEB-INF in the tomcat/conf folder on Windows, and Ubuntu dumped it at the top level folder for my websites...very odd.
So I cleaned that up and changed it to webapps too (keeping with the standard defaults :)
And I thought about the SVN Ignore...I have ignored it in Eclipse ;) and just have not done it in the svn client stuff yet.
<classpath codebase="deploy/jboss-web.deployer/railo-3.1.0.012/lib" archives="*" />
... the railo java libraries the following jboss service are no long accessible form the web:
* Tomcat status (full) (XML)
* JMX Console
* JBoss Web Console
Do you know who to link and still retain the jboss web console>?
I've always removed all other apps when installing Railo jars "globally" like this. I generally do this with Tomcat, not JBoss, but same idea. I'm not surprised that there could be conflicts with other Web apps when the Railo jars are loaded this way. I doubt it's worth fighting it much. I'd suggest using just Railo with your servlet container instance this way (no other Web apps on the instance), or run Railo as separate WARs for each app.
Actually, with a second glance at your comment, I see that you mentioned these other apps are not accessible -- are they returning 404 errors, or are you getting other errors? If not 404, you can check the logs for error details, but again, I doubt it's worth the fight.