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.

BonCode

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.

JDK required

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.

Not so wonderful wizard

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 index.cfm.

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.

Connecting Railo to IIS (7/8) manually

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.

1. Prepare Java

Before starting, ensure that your JAVA_HOME environment variable points to a JDK.

2. Prepare IIS

1. Ensure you have the .NET framework (3.51 or above) and the .NET extensibility feature installed.

   

   (NB: use the Programs and Features > Turn Windows features on or off UI and not the Web Platform Installer.)
2. Ensure Feature Delegation is enabled for "Handler Mappings". Check the Feature Delegation section under Management from the root IIS UI view:

   

   This will allow the handlers to be individually customised for our Railo site.

3. In the IIS Manager UI, create an application pool for Railo which uses .NET (as apposed to "no managed code") in "Integrated" pipeline mode.

   

4. Create a new website for Railo, assigning it to the new Railo App Pool.

3. Install Railo without the BonCode connector

1. Run the Railo installer but de-select the option to install the BonCode connector. The connector files will be copied into the Railo root, but the auto-installer will not run.
2. Once Railo and Tomcat are installed, add a <Host> entry for the new railo website in [railo-root]/tomcat/conf/server.xml.
3. Restart the Railo/Tomcat service so that a WEB-INF folder is auto-created in the new web context.

4. Copy the BonCode connector files

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:

• BonCodeAJP13.dll
• BonCodeIIS.dll
• BonCodeAJP13.settings

(* 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.)

5. Configure the Handlers for the Railo site

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.