ColdFusion on a Stick
How to Create a Portable "Plug 'n Play" CF Application

by Megan Garrison

Introduction

I first became interested in the idea of portable, stand-alone ColdFusion applications when I read a series of articles by Phil Cruz and Dick Applebaum in CFDJ about the CFEverywhere concept. With trial and error I eventually created my own prototype CFEverywhere app using the Railo CFML Engine on Jetty J2EE Java HTTP Server with HSQLDB for the database.

The process proved a wonderful learning experience for me, however I felt less than happy with my own end results primarily because anything I created this way wasn't going to be exactly "Plug 'N Play." Since the servers and database were all java, anyone who wanted to use a CFEverywhere app would be required to first download and install Java Runtime 1.4.x  (approx. 15 mb) I had a hard time seeing this happening. There are other reasons I stopped at this point, but they aren't really relevent to this tutorial. NOTE: The J2SE Java Runtime Environment (JRE) allows end-users to run Java applications. It is NOT the same thing as the Software Development Kit (SDK) which supports creating J2SE applications.

Anyway, even tho I had reached a personal stopping place in my CFEverywhere experiments, I couldn't seem to drop the idea of being able to create some simple, portable, stand-alone ColdFusion apps that could run off a flash drive or USB memory stick (hence the name ColdFusion on a Stick) or possibly even a CD or DVD.  My current experiment isn't actually "CFEverywhere" because it is a Windows only solution and not cross-platform, but it's a start.

Okay, enough introduction. Let's begin...

Step 1. Download & Unpack Uniform Server

Download The Uniform Server from http://prdownloads.sourceforge.net/miniserver/UniServer3_3.exe?download.

(The Uniform Server is a lightweight (5.79 MB) free open source "WAMP" project which combines pre-configured versions of the Apache web server, MySQL database and PHP & Perl scripting languages and runs on any MS Windows OS based computer.)  It requires no installation; it does not wrte anything to the registry.  To unpack and run, just double-click the .EXE and extract the files to your hardrive.  For the purposes of this tutorial, we'll extract them directly onto  c:\

You will end up with a folder of files named, "Uniform Server" (c:\Uniform Server)

Rename the folder to something short with no spaces.  I will rename mine, cfoas, (an acronym for "ColdFusion on a Stick"). Ok lets explore the folder structure just a little. First thing to note is that Uniform Server creates a RAM disk with a virtual drive labeled with the letter, "W". (If "drive W" is already taken, see this under "you might need to know") Under the diskw folder you will find:

www - where your .cfm templates will go cgi-bin - for any perl scripts, etc. home - server admin scripts & screens usr - PHP, PERL, and MySQL engines tmp - directory for temporary files

Uniform Server uses port 80, so if you are running IIS or Skype or anything else on port 80 you will need to turn them off for the moment.

If nothing is running on port 80, open up the newly renamed (cfoas) folder, and double-click Server_Start.bat

A console panel will come up briefly and then a purple web page will open up and forward you to your web server control panel at http://localhost/apanel/ - (NOTE: If your anti-virus pops up an alert notifying that apache is trying to connect, allow the connection.)

OK! Uniform Server is running. You can use the arrow buttons at the bottom of the window to scroll the Menu and content areas. When you have finished exploring, you can double-click stop.bat in the cfoas folder or Click the "Shutdown Server link" in the left menu .

If you chose the later, a "Varify Shutdown" page will appear in the content area. Click the "Shutdown" link to stop the server. The console will appear again briefly and the content area page will display a "The page cannot be displayed" Cannot find server or DNS Error Template. You can now close the browser window and go on to step 2.

Step2-A. Download & Unpack IgniteFusion

Download IgniteFusion from http://www.ignitefusion.com/download.htm

IgniteFusion is a small (1.2 MB) non-java freeware ColdFusion compatible script engine that runs ColdFusion scripts. For more info on IgniteFusion, you can Check CF5/CFMX Compatibility here and read their FAQs here.

Create a folder named, "if" under the diskw\usr\local directory (diskw\usr\local\if) then unzip the IgniteFusion28r.zip file and extract just the ignitedb.exe file (& the License.txt file if you want) into this new directory.

Step2-B. Installing Ignite Fusion on Universal Server

Go to diskw\usr\local\apache2\conf\ and open the httpd.conf file in a TEXT editor. Take a moment to familiarize yourself with it's contents. Scroll down to around line 303 and look for a line that says, "# Note that from this point forward you must specifically allow"

Modify the httpd.conf file by putting the following code above the aforementioned line.

#ignite stuff ----START ---

#create virtual directory to point to the directory where IgniteDB.exe exists
ScriptAlias /if/ "/usr/local/if/"

#Add extensions associations
AddType application/x-httpd-ignitedb .ign .cfm .cfml

#Tie extensions to executable
Action application/x-httpd-ignitedb "/if/ignitedb.exe"

#ignite stuff ---- END ---

Save the modified file. Create a simple hello world "testme.cfm" template and put it in the \diskw\www directory. Start the server and navigate to http://localhost/testme.cfm to confirm everything is working properly.

Step 3. Connecting to an Access Database

If this was a regular server situation, you would want to put your access database above the webroot. But in this case our goal is to creat a portable app that could run off a flash drive or USB memory stick making the location of the access database a moot point. So just put your mdb file either directly into the www folder or creat a folder in the webroot and name it "data" or whatever and put your .mdb file in there. For the purposes of this tutorial we will just put it directly in the www folder.

Go back to your testme.cfm template. In order to connect to the access database you will need to create a DSN-less connection to the database like so:

<cfquery name="qry_name"
dbtype="dynamic"
connectstring="Driver={Microsoft Access Driver(*.mdb)};Dbq=#ExpandPath('\')#mydatabase.mdb;Uid=Admin;Pwd=;ReadOnly=1;Exclusive=1;">
SELECT fld_Name1, fld_Name2 From tblName
</cfquery>

output your data

<cfoutput query="qry_name">
#fld_Name1# - #fld_Name2#<br>
</cfoutput>

Step 4-A. Implementing the MySQL Database

As mentioned in step 1, Uniform Server comes with a MySql Database. You can turn on the included MySQL database server by clicking the "Run MySQL" link in the left-hand menu of the control panel under "Server Start".  Then use the arrows to scroll down and click "PhpMyAdmin" under "Tools." A new window will open containing the PhpMyAdmin Home page. You may want to take a moment to create a new database with at least one table and a couple of fields for tutorial testing purposes. If you are not familiar with MySQL you can find a MySQL Tutorial here

To continue, the problem with connecting to the included MySQL database is that IgniteFusion does not currently have a DSN-less process for MySQL. ODBC drivers for MySQL need to be installed. So, we will need MyODBC Windows No Installer (zipped DLLs) (download links are below the form).

Step 4-B. MyODBC Drivers

Download the zipped DLLS. Unzip and extract the contents into diskw\usr\local\ This will create a folder named,"mysql-connector-odbc-noinstall-3.51.12-win32" . Rename it to "myodbc". Inside the myodbc folder you will see a number of .rtf files - remove these along with the "Doc" folder to your My Documents folder (or whereever) leaving only the Install.bat, Uninstall.bat and the lib and bin folders. Move everything in the bin and lib folders up into the myodbc folder and delete the now empty bin & lib folders. You can delete the dltest.exe and convert the License.rtf to License.txt and save it back into the myodbc folder. Your mydobc folder contents should now look like the image on the right.

Ok so, the aim of this experiment is to keep the app portable. I didn't like having to ask end users to download and install Java Runtime and likewise MyODBC so I decided to see if I could get the MyODBC drivers to install on server startup and uninstall on shutdown. This involves writing to the registry. See this warning Meanwhile I will share what I did on my own machine.

I renamed Install.bat to Install.ini and rename Uninstall.bat to Uninstall.ini

I then opened Install.ini in a TEXT editor and deleted everything above the bottom line (myodbc3i -a -d -t"MySQL ODBC 3.51 Driver;DRIVER=myodbc3.dll;SETUP=myodbc3S.dll"). This line contains information needed to create my new registry entry. "MySQL ODBC 3.51 Driver" is the Driver name. "DRIVER=myodbc3.dll" points to the driver and "SETUP=myodbc3S.dll" points to the library needed for setup.

My new Install.ini content looked like this:

REGEDIT4
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers]
"MySQL ODBC 3.51 Driver for Megan"="Installed"

[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\MySQL ODBC 3.51 Driver for Megan]
"Driver"="W:\\usr\\local\\myodbc\\myodbc3.dll"
"Setup"="W:\\usr\\local\\myodbc\\myodbc3S.dll"

IMPORTANT NOTES:

• Notice I changed the Driver Name from "MySQL ODBC 3.51 Driver" to "MySQL ODBC 3.51 Driver for Megan". this is incase someone already has myodbc drivers installed on their machine. We would not want them to be overwritten with different information and then uninstalled, so it is important to use a unique driver name.
• The first line, "REGEDIT4" MUST be there or the ini will not be allowed to write to the registry.
• the last line from the original .bat file (myodbc3i -a -d -t"MySQL ODBC 3.51 Driver;DRIVER=myodbc3.dll;SETUP=myodbc3S.dll") was deleted as soon as I had the necessary information.

I then opened Uninstall.ini and modified it so the content looks like this:

REGEDIT4
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Drivers]
MySQL ODBC 3.51 Driver for Megan=-

[-HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\MySQL ODBC 3.51 Driver for Megan]

To call Install.ini on server startup, I opened Server_startup.bat and placed the following line

regedit /S diskw\usr\local\myodbc\install.ini

after "rem use: start nomysql console - to display console" (approx. line 11)

To call Uninstall.ini on server shutdown, I opened stop.bat and placed the following line

regedit /S diskw\usr\local\myodbc\uninstall.ini

after "@echo off" (approx. line 7)

IMPORTANT NOTES:

• /S is to surpress windows alert popups, i.e. silent, so people dont have to hit Yes and then OK in the popup.
• I never would have been able to work out this part of things without the advice of EasyCFM.com memeber, Maquiladoras

I then started up uniform server, then ran regedit to see if the new myodbc driver was listed. Happily, it was. Likewise, when I ran stop.bat, and ran regedit, the new new myodbc driver was no longer there.

Step 4-C. Connection to MySQL

To see if I could now connect to MySQL, I created a simple Application.cfm containing the following:

<cfset request.connect="driver={MySQL ODBC 3.51 Driver for Megan}; database=mytestdb;server=localhost;uid=root;pwd=root;option=16386;">

In my testme.cfm

<cfquery name="qry_name"
dbtype="dynamic"
connectstring="#request.connect#">
select fld_name1, fld_name2
from tblname
</cfquery>

<cfoutput query="qry_name">
#fld_name1# - #fld_name2#<br>
</cfoutput>

Step 5. CF in a Flash

Ok, I know the title of this tutorial is "ColdFusion on a Stick." I chose that because the name fit the idea of putting the app on a USB Memory stick + it made me laugh :D. In actuality, I tested the portability part of my concept on a 256 MB Flash Drive. Everything worked - slower, of course, but it worked!. Disk space used at this point was around 38MB. I then went downstairs and plugged the Flash drive into my husband's computer - worked fine there too. If you want the to have the browser open on your testme.cfm page rather than the uniform server admin panel, open diskw\home\admin\www\refresh.html in a text editor. get rid of the javascript redirect and add the following code to the document head:

<meta http-equiv="refresh" content="10;url=http://localhost/testme.cfm"> (you may have to play with the time delay interval - flash drives are slower than your regular drive and it will take longer for the servers to start).

You might also want to add a little "Starting Servers..., Please Wait..." message to the content area.

Still left to do:

• figure out how to make an autoplay that will work on a flash drive.
• get it going on a CD

You Might Need to Know

• If port 80 is already taken - If there is already a webserver active on port 80 you can switch uniform server to another port, for example 81. To exchange :80 for :81, edit Listen and ServerName settings in the httpd.conf file.
  
• If Drive "W" is taken - If your PC has a hard drive called 'W' already, you can modify the Start.bat or launch the Disk Start.vbs file to chnage the drive to another letter. Then go to diskw\home\admin\www\includes and open config.inc.php in a text editor and change $drive = "W:"; to reflect your new drive letter.
  
• If you want MySQL to start automatically on server start - open Server_Start.bat and about line 28 remove the IF statement from 'IF "%2"=="mysql" start \usr\local\mysql\bin\mysqld-opt.exe --defaults-file=/usr/local/mysql/bin/my-small.cnf' so that it reads:
  start \usr\local\mysql\bin\mysqld-opt.exe --defaults-file=/usr/local/mysql/bin/my-small.cnf (If your anti-virus kicks up an alert when mysql goes to connect, allow the connection.)
  
• Warning about editing the Windows registry - Changes made to the Windows registry happen immediately, and no backup is automatically made. Do not edit the Windows registry unless you are confident about doing so. Microsoft has issued the following warning with respect to the Registry Editor:

  "Using Registry Editor incorrectly can cause serious, system-wide problems that may require you to re-install Windows to correct them. Microsoft cannot guarantee that any problems resulting from the use of Registry Editor can be solved. Use this tool at your own risk."

Resources

The Uniform Server

• Download
• Wiki

IgniteFusion

• Download
• Check CF5/CFMX Compatibility
• FAQs

MyODBC

• Windows No Installer (zipped DLLs)

CFEverywhere

• CFEverywhere Part 1 in CFDJ - Intro to CFEverywhere
• CFEverywhere Part 2 in CFDJ - How to configure the database
• CFEverywhere Part 3 in CFDJ - How to make a double-clickable application
• CFEverywhere mailing list
• Railo CFML Engine
• Jetty J2EE Java HTTP Server and Servlet Container
• HSQLDB Database Engine