Clone wiki

Lucee / Migrate from Railo


Migrate from Railo (c)

Lucee is forked from the Railo CFML Server (Version 4.2) so you can easily migrate an existing Railo installation as follows.

Please read all the instructions before you get started.

Lucee will rewrite some of the configuration files in your existing installation. It will also do a backup of the original contents as a zip file (see below) in case you need to roll back, but it's advisable to make a backup of the original installation just in case.

  1. Download the lucee-[version] package from our download section and unzip it somewhere.
  2. Stop your Railo server.
  3. In the zip file you will find a file called lucee.jar. Use that JAR to replace the existing railo.jar in your Railo installation's lib directory. Important: make sure you remove the railo.jar completely. Do not just rename it (e.g. to "railo.jar.bak"), otherwise most servlet engines will still pick it up!
  4. Replace the rest of the jars in the lib directory with the jars from the zip file. The jars have the same names as the original files so you can simply copy them to the directory.
  5. Restart your Railo Server which will now convert itself into a Lucee Server.

When it first starts, Lucee rewrites the server context and all individual web contexts. All the changes made are logged in detail to the application.log log file. To see these entries make sure the application.log file has set the log level "Info" or less. In the process Lucee does a backup of each original context in a zip file named using the pattern "railo-[server|web]".

IIS BonCode connector

If you are using the BonCode connector for IIS/Tomcat, you may need to update to the 1.0.20 (or later) version which supports Lucee.

  1. Download version 1.0.20 (or later)
  2. From the AJP13 folder inside the downloaded zip, copy the following 2 files to the BIN directory in each of your web roots, replacing the existing files:
  • BonCodeAJP13.dll
  • BonCodeIIS.dll

Server/Web administrator URLs

To access the server admin and individual web context admin GUIs, you will need to replace "/railo-context/" in each URL with "/lucee/". For example instead of


you should now use:


Optional Steps

Lucee only converts the Railo config settings, it does not touch your Servlet Engine configuration since Lucee will work with the existing Railo configuration.

web.xml (jetty)/webdefault.xml (tomcat)

You can for example change the class names in the servlet definitions from

    <description>CFML runtime Engine</description>
        <description>Railo Web Directory directory</description>
        <description>Directory where Lucee server root is stored.</description>
    <description>CFML runtime Engine</description>
        <description>Lucee Web Directory directory</description>
        <description>Directory where Lucee server root is stored.</description>
but doing so isn't necessary and makes no difference to Lucee. When you change a path like "D:\projects/whatever/railo/server" to "D:\projects/whatever/lucee/server", Lucee will no longer find the original configuration and because of that not migrating it, so it is really better to changes paths like this AFTER the migration!

The same applies to the "railo-inst.jar" defined in your start script: you can change it but it is not necessary.


Partially or fully Java based extensions that rely on certain Railo interfaces may not work and could possibly prevent Lucee from starting.

The following extensions need to be updated in order to work with Lucee. It is best uninstall them before you migrate then re-install them afterwards so that you get the new Lucee compatible versions:

  • All cache extensions (Memcached, Infinispan)
  • MongoDB extension

This list will be added to as issues come to light.


The original Railo extension produced by TeamCfAdvance is not compatible with Lucee and should be removed.

However a modified version by Andrew Kretzer is now available and can be installed in Lucee by carefully following the instructions provided.

Alternatively, a standalone (non-extension) spreadsheet library for Lucee is available which supports almost all of the extension's functionality.


If you have installed the Video extension, you may see the following error: java.lang.NoClassDefFoundError: railo/runtime/video/VideoExecuter. To fix this simply download the railo-video-extension-adapter-for-lucee.jar and place it next to the "railo-extension-video.jar" in your installation.

##org.railo.cfml... component paths

If you have used the component path org.railo.cfml... as a return or argument type, it must be changed to org.lucee.cfml, eg.

org.railo.cfml.Query function newQuery(){
   return new Query();
These CFCs may be affected:


###objectSave() Objects persisted with objectSave() on Railo, can not be loaded with objectLoad() on Lucee.

###Other issues?

If you are having problems please post to the Lucee Google Group.