I've been meaning to give Railo a spin for quite a while, but the complexity of setting up a separate dev environment has been partly behind my procrastination.
Wouldn't it be nice if you could simply plug it into your existing web server without conflicting with what's there already - in my case IIS 8 and ColdFusion 9?
Well it seems you can.
The current full Railo/Tomcat installer includes a nifty utility called the BonCode Connector which allows Tomcat to be hooked up to IIS on a per site basis without interfering with existing ISAPI handler mappings (used to connect CF9), since it uses a different, .NET based mechanism.
However, my initial attempt at letting the Railo 4.2 installer (version 4.2.1.000-pl2) do the work didn't go smoothly.
Towards the end of the process it failed saying that it could not start the Railo (windows) service. A service called "Railo" had been created but wasn't running and I was unable to start it manually.
From the installation logs I gleaned that it expected my
JAVA_HOME environment variable to point to a JDK runtime. Mine was pointing to a standard version 7 JRE, which I keep updated with security patches. I'm not sure this is a reasonable expectation on the part of the installer, but in any case it would have been helpful to have been warned that this was a requirement, preferably in advance.
Having pointed my
JAVA_HOME to a JDK, the installer ran successfully.
I opted not to install the BonCode connector during the Railo installation preferring to run it separately, which I did, taking care to apply it only to the specific IIS site I'd prepared for Railo.
Despite this, I was disappointed to discover that the BonCode connector appeared to have ignored my wishes. The Tomcat handler mappings had been installed at the root level (applicationHost.config) from which all sites inherit their settings (along with a whole bunch of other handler mappings I didn't want). To add insult to injury, when I then uninstalled BonCode, it promptly reset the root "Default document" settings to the IIS defaults, wiping out
Result: none of my existing CF sites worked any more.
Restoring things to how they were was just a matter of removing the BonCode handler mappings (along with the other unneeded handlers it had added) and replacing the default document settings, but my trust in installer wizards was diminished.
Despite its apparent faults, the BonCode package does come with some very detailed documentation, including steps for manual connection. My experience suggests this is probably the best way to approach things and so here are my own step-by-step instructions based on what seems to have worked for my particular circumstances.
Before starting, ensure that your
JAVA_HOME environment variable points to a JDK.
(NB: use the Programs and Features > Turn Windows features on or off UI and not the Web Platform Installer.)
This will allow the handlers to be individually customised for our Railo site.
<Host>entry for the new railo website in [railo-root]/tomcat/conf/server.xml.
In the root folder* of the website to connect to Railo, create a folder called
BIN and copy the following files from the [railo-root]/AJP13 folder:
(* i.e the document root folder of the host, even if the application uses a physical or virtual folder below that root. So if the app URL is railo.local/myapp, the
BIN folder needs to go in the document root for railo.local.)
In the Railo web root, create a web.config file containing the following settings to replace the root CF9 handlers with the local BonCode mappings:
<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <handlers> <remove name="cfrHandler" /> <remove name="cfmHandler" /> <remove name="cfcHandler" /> <remove name="JWildCardHandler" /> <!--It's best to remove values before adding them in case they have been already added by a parent config, which will cause a 500 error--> <remove name="BonCode-Tomcat-CFM-Handler" /> <remove name="BonCode-Tomcat-CFC-Handler" /> <add name="BonCode-Tomcat-CFM-Handler" path="*.cfm" verb="*" type="BonCodeIIS.BonCodeCallHandler" modules="ManagedPipelineHandler" resourceType="File" requireAccess="Script" allowPathInfo="false" preCondition="integratedMode" /> <add name="BonCode-Tomcat-CFC-Handler" path="*.cfc" verb="*" type="BonCodeIIS.BonCodeCallHandler" modules="ManagedPipelineHandler" resourceType="File" requireAccess="Script" allowPathInfo="false" preCondition="integratedMode" /> </handlers> </system.webServer> </configuration>
20 October 2014: It is possible that your global ColdFusion handlers have different names to the above (i.e. JWildCardHandler etc). Check in the root Handler Mappings section of the IIS Manager, and if necessary adjust your web.config
remove directives to use the names you find.
The Railo site should now run, with existing CF9 sites unaffected.Back to the top