Running Railo on Windows with IIS in production

Railo is a free, open source CFML engine, that  is released under the GNU license. It is known to be highly performing and supported CFML engine available.  Most existing ColdFusion applications will work on it. This article provides simple instructions how to install Railo on IIS web server in production. This solution can be used to run CFML applications on your Windows servers or provide CFML hosting to others.

Environment installation

First we need to configure the Windows server to run CFML applications. Please follow these instructions:

1. Download and install Microsoft Web Platform Installer.
2. Run Web Platform Installer and click “Options”.
3. Add Helicon Zoo feed into “Display additional scenarios” box: http://www.helicontech.com/zoo/feed. New “Zoo” tab will appear.
4. Go to the Zoo –> Engines and install Railo 3 or Railo 4 (or both).

   

   Alternatively you can install Zoo –> Packages –> CFML Hosting Package. This will install both Railo 3 and 4 and all other requirements to host CFML applications on IIS.

   

5. Accept licenses to start installation process.

All required packages and dependencies will be downloaded and installed. Whole installation process may take time. After installation is completed your server is ready to run CFML applications as usual IIS web sites.

Usage

To create new Railo web site you can use Web Platform Installer again. Go to Zoo –> Templates and install Railo 3 or Railo 4 project.

You can set either IIS or IIS Express as target environment for this project and if you have not installed CFML Hosting Package, then all required dependencies will be installed automatically. After installation is completed Railo web site will start working immediately.

If you want to create Railo web site manually, please add an empty IIS web site for your application:

Create web.config file in the web site folder and put the following content into it:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="railo.project">
        <environmentVariables>
        </environmentVariables>
      </application>
     </heliconZoo>
    <handlers>
      <add name="railo.project#x86.cfm"   scriptProcessor="railo" 
        path="*.cfm"   verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfc"   scriptProcessor="railo" 
        path="*.cfc"   verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfml"  scriptProcessor="railo" 
        path="*.cfml"  verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfr"   scriptProcessor="railo" 
        path="*.cfr"   verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x86.cfswf" scriptProcessor="railo" 
        path="*.cfswf" verb="*" modules="HeliconZoo_x86" 
        preCondition="bitness32" resourceType="Unspecified" 
        requireAccess="Script" />
      
      <add name="railo.project#x64.cfm"   scriptProcessor="railo" 
        path="*.cfm"   verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfc"   scriptProcessor="railo" 
        path="*.cfc"   verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfml"  scriptProcessor="railo" 
        path="*.cfml"  verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfr"   scriptProcessor="railo" 
        path="*.cfr"   verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
      <add name="railo.project#x64.cfswf" scriptProcessor="railo" 
        path="*.cfswf" verb="*" modules="HeliconZoo_x64" 
        preCondition="bitness64" resourceType="Unspecified" 
        requireAccess="Script" />
    </handlers>
    <defaultDocument>
      <files>
        <remove value="index.cfm" />
        <add value="index.cfm" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

This will enable Railo 3 to process requests for the registered file extensions in this IIS web application folder. To use Railo 4 set scriptProcessor=”railo.4″ instead. As there is no currently application files in this folder navigating to the root of the web site will trigger 403 error. So please navigate to the http://localhost/railo-context/admin.cfm to open Railo administration interface. For the first start you will be asked to create server and web administrator passwords.

After that you may just put your CFML application into this IIS web site folder.

Manual installation

Sometimes you may need to install specific version of Railo, or you may only want to install Railo for a specific IIS web site instead of installing it on a server globally. There could be a case when your hosting service does nto provide Railo support, but instead has support for generic Java applications. In this situation please follow this instruction:

If you are installing on your own server first you need to follow first three steps from “Environment install” chapter to get Helicon Zoo feed in Web Platform Installer. Now go to Zoo –> Packages and install Java Hosting Package. This will install support for generic Java applications for IIS.

Then go to the Railo Download page and get the WAR archive distribution version. Put this WAR file into IIS web site root folder and create a web.config file there with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="jetty.project" >
        <environmentVariables>
          <!-- Uncomment line below if you want to set contexts directory -->
          <!--  <add name="CONTEXTS_DIR" value="%APPL_VIRTUAL_PATH%" /> -->

          <!-- Optional variables: -->
          <!-- <add name="CONTEXT_PATH" value="%APPL_VIRTUAL_PATH%" /> -->
          <!-- <add name="WAR_EXTRACT_PATH" value="%APPL_PHYSICAL_PATH%" /> -->

          <!-- A WAR file or start directory to run -->
          <add name="WAR_FILE" value="railo-3.3.1.000.zip" />
        </environmentVariables>
        </application>
    </heliconZoo>

        <handlers>
          <add name="jetty.project#x86" scriptProcessor="java.jetty" 
            path="*" verb="*" modules="HeliconZoo_x86" 
            preCondition="bitness32" resourceType="Unspecified" 
            requireAccess="Script" />
          <add name="jetty.project#x64" scriptProcessor="java.jetty" 
            path="*" verb="*" modules="HeliconZoo_x64" 
            preCondition="bitness64" resourceType="Unspecified" 
            requireAccess="Script" />
        </handlers>
  </system.webServer>
</configuration>

Note the name of the file here is railo-3.3.1.000.zip. You may need to change it if your version of Railo is different. Also as you can see handlers are mapped to the asterisk – “*”, which mean every request to this web site will be processed by Java, including static files. Sometimes this is a good idea, especially if you are using some kind of URL rewriting or request filtering tools in your Java or CFML application. We have chosen to use asterisk map as it is more generic and will provide better application compatibility. But if you feel confident in server configuration, mapping handlers to specific file extensions (as it is done in web.config from automatic installation chapter) will give you some performance points, as static files will be processed directly by IIS.

Now you can navigate your browser to the web site root, which will bring you Railo welcome page. Then simply put your CFML application in this IIS web site folder to start working with Railo!