As simple as possible, as complex as necessary

Manually connecting Lucee to an IIS website

10 March 2016

Lucee can be installed on Windows/IIS very easily using the installer, but by default this will connect it to all of your IIS websites.

This may be appropriate if all or a large number of sites on the server require Lucee, but we prefer to enable it selectively for each individual site.

Doing so is pretty straightforward and I detailed the steps involved in a previous post written when I was first experimenting with Railo.

As that post was primarily about running ColdFusion and Railo together, I thought I'd separate out the steps we've continued to use even though we're now only running Lucee.

Prepare to install Lucee

There are a few things to check before running the installer to ensure things go smoothly.

  1. Ensure a Java JDK is installed, as opposed to a standard JRE (more details on Java download options from Oracle).
  2. Ensure you have a JAVA_HOME environment variable pointing to the JDK (Atlassian have some instructions).
  3. Ensure the .NET Framework 3.5 or higher and the .NET extensibility feature are both installed as part of IIS.

    screenshot of adding windows features

  4. In the IIS Manager, ensure Feature Delegation is enabled for "Handler Mappings". Check the Feature Delegation section under Management from the root IIS UI view:

    screenshot of Feature Delegation UI

    This will allow the handlers to be individually customised for each Lucee site.

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

    screenshot of Application Pools UI

  6. Assign your Lucee website to the above application pool using the Basic Settings dialogue panel.

    screenshot of IIS basic settings edit panel

Install Lucee without the BonCode connector

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

Copy the BonCode connector files

In the root folder* of the website to connect to Lucee, create a folder called BIN and copy the following files from the [lucee-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, the BIN folder needs to go in the document root for

Add the handlers for the Lucee site

In the application's web root, ensure you have a web.config file containing the following BonCode handlers:

<?xml version="1.0" encoding="UTF-8"?>
            <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" />

If you use extensions other than .cfm and .cfc for Lucee, then you'll need to add handlers for those as well.

Adding further Lucee sites

To enable Lucee for another website, simply:

  1. Ensure the site is using an IIS App Pool with .NET/integrated pipeline enabled (could be the same pool as the others or one dedicated to the site/application).
  2. Add a copy of the BIN folder to the site's host root directory.
  3. Ensure the site's web.config file contains the Boncode CFM and CFC file handlers.
  4. Add a host entry for the site in Lucee's server.xml and restart.

Posted on .


  • Formatting comments: See this list of formatting tags you can use in your comments.
  • Want to paste code? Enclose within <pre><code> tags for syntax higlighting and better formatting and if possible use script. If your code includes "self-closing" tags, such as <cfargument>, you must add an explicit closing tag, otherwise it is likely to be mangled by the Disqus parser.
Back to the top