Moving ColdFusion applications from Windows to Linux

Posted on May 24, 2007

This subject came up a few weeks ago on the DFW CFUG mailing list and again this week on the CF-Talk list. Here are some of the issues you’ll face when moving a Coldfusion application from Windows to Linux.

Linux has a case-sensitive file system.

On Windows, index.cfm is the same file as Index.cfm. On Linux, they are two separate files. Databases on Linux also have ties to the file system, so your SQL will have to be checked as well.

The built-in Coldfusion tags, thankfully, are not case-sensitive.

Application.cfm not application.cfm

I asked about this years ago and I believe it was Ben Forta who replied that when the Linux version of Coldfusion was first compiled, the file’s name just happened to be specified as Application.cfm in the build, so it’s been like that ever since.

Regardless of the actual reason, on Linux you have to specify these exact cases for these files to be treated correctly by the Coldfusion server:

  • Application.cfm
  • OnRquestEnd.cfm (thanks Peter)
  • Application.cfc

File’s name is “hello.cfm”.

<!--- Valid --->
<a href="hello.cfm">Hello</a>
<!--- Invalid --->
<a href="Hello.cfm">Hello</a>
<a href="HELLO.CFM">Hello</a>

This will most likely been the hardest thing to fix manually, but DreamWeaver makes fixing this a piece of cake.


File’s name is “hello.cfm”.

<!--- Valid --->
<cfinclude template="hello.cfm" />
<Cfinclude template="hello.cfm" />
<CFINCLUDE TEMPLATE="hello.cfm" />
<cfinclude template="Hello.cfm" />
<cfinclude template="HELLO.CFM" />

Custom Tags

You’ve created a custom tag called showMessage.cfm. You can call this file using cfmodule or using the cf_ prefix.

<!--- Valid --->
<cfmodule template="showMessage.cfm" />
<cfmodule template="showmessage.cfm" />
<!--- Valid (6+), Invalid (<= 5) --->

With Coldfusion 4.x and 5 on Linux, any CFM file that was called as a custom tag using the cf_ prefix had to be completely lowercase: showmessage.cfm (not showMessage.cfm).

<!--- Valid --->

As of ColdfusionMX (version 6), <cf_showMessage> and <cf_showmessage> are both valid syntax regardless of the file’s case.

Can I still use my CFX Custom Tags on Linux?

For C++ CFX tags, you may need a version that has been compiled on Linux. If the CFX tag is a Windows .DLL file, without the source code you may be out of luck.

Can I still use my MS-Access database on Linux?

My first recommendation is to convert your MDB file to an actual Relational Database Server. Why? Because I believe this article still holds true: Nine Reasons NOT To Use MS Access To Power A DB-Driven Website. Maybe the latest version of MS-Access doesn’t have as many limitations, but odds are the MDB file for an older CF Application is from an old version of MS-Access.

Two free database servers that are native to Linux are MySQL and PostgreSQL. MySQL has made converting an MDB file a simple process using their MySQL Migration Toolkit. After a few clicks your Access database tables, indexes, views, etc. have been converted to MySQL (data included). I’m sure there are MDB to PostgreSQL converters as well, but I’ve not used any.

If you can connect to a MS SQL Server database on a separate Windows server, you can import the MDB file using SQL Enterprise Manager.

It shouldn’t take long to verify if your cfqueries still work unless the application is using SQL generated by MS-Access. Often SQL generated by MS-Access isn’t standard SQL and will not work with other databases.

If moving away from MS-Access is not an option, then you can try connecting to the MDB file using a JDBC-ODBC bridge. Wayne Graham has a post outlining this process. I’ve not tried this myself, so I’m unsure of what limits may exist using this type of connection.

Databases and Queries

When using MySQL on Linux, database names, database table names and aliases of table names are tied to the file system and are therefore case-sensitive. If you have problems defining a datasource in the Coldfusion Administrator, check the exact name of your database.

Given that so much of a Coldfusion application can be tied to the database, this has always been the biggest headache for me when moving an application to Linux. Especially when it’s one I’ve inherited.

Here we have a MySQL database table named “someTable” with a column named “ID”:

<!--- [1] Invalid --->
  someTable A

<!--- [2] Invalid --->
  sometable a

<!--- [3] Valid --->
  someTable a

<!--- [4] Valid --->
  someTable a

In the case of #1, the table name is correct, but the table’s alias doesn’t match the column’s prefix. In the case of #2, the alias and prefix match, but the table name is the wrong case.

#3 is juuuust right.

#4 is also correct because database column names are not tied to the file system, so you can reference them with any letter case. However, I’d still recommend using the exact case defined in the database for consistency’s sake.

PostgreSQL handles identifiers (i.e. table and column names) a bit differently. According to section 4.1.1 of the documentation, PostgreSQL considers table names to be lowercase, even when they are written in uppercase, unless surrounded by double quotes.

/* creates a table named foo */

/* creates a table named FOO */

/* creates a table named FOO */

/* looks for a table named foo */

/* looks for a table named FOO */

> SELECT * FROM "foo"
/* looks for a table named FOO */

Always check the documentation for whichever database server you choose to see if case-sensitivity is an issue.

The application is running, but charts don’t work

Linux servers most often run in “headless” mode. This means that there is no GUI (no X11 or X Server) so graphics can not be rendered. This causes CFCHART, java image manipulation (i.e. CAPTCHAs) and I think even Flash forms to go missing unless the server is configured correctly.

Doug Hughes has a great post addressing this issue. The last paragraph has links to more resources.

We’re upgrading our version of Coldfusion while we’re at it

Changing operating systems can be frustrating enough, but if you’re moving from a pre-MX (6) version of Coldfusion to the latest and greatest just make sure you give yourself time for QA.

Around 2001, we migrated a group of large CF applications built in 1999 on Coldfusion 4 for Windows to Coldfusion 4.5 for Linux. The only code changes needed during the move were to address case-sensitivity issues.

They are currently running on ColdfusionMX 6.1 with no code changes outside of functionality updates.

About the Author
Adrian J. Moreno

Adrian is a CTO and solution architect specializing in software modernization. More information