Installing ColdFusion MX on Mac OS X

These instructions apply to ColdFusion MX 7 - now that ColdFusion MX 7.0.1 is available, these instructions are obsolete because 7.0.1 has a full native Mac OS X installer. Just double-click and install! Enjoy!

A lot of ColdFusion developers are switching from Windows PCs to Apple Macs and although the Mac has a very friendly and intuitive user interface, they are not used to working at a Unix command-line and so they have a hard time figuring out exactly how to get ColdFusion MX up and running on their shiny new Mac. I've done a lot of installs myself and I've talked a lot of people through it on IM chat so I figured it was about time I published my quick, step-by-step instructions for the installation.

There's a couple of things you need to know about CFMX on OS X that are different from CFMX on Windows. The two biggest differences are that you'll be dealing with the J2EE installation and that there is no simple, integrated installer so you're in for some command-line exercise.

What you'll need for this installation:

What you'll need to be familiar with:

Installing and Updating JRun

Double-click the JRun installer and accept all of the defaults. This should give you a standard installation in /Applications/JRun4.

Open the Terminal application and go to your desktop (or wherever your browser downloaded the updater) and run the updater shell script. For example:

(or whatever the current Unix updater file is called). When prompted for the directory to install the updater, make sure you enter /Applications/JRun4 because the default offered by the installer (something like /Applications/JRun4 Updater) is not correct!

Now you should be able to start the JRun Management Console (JMC) by going to the JRun installation's binary directory and firing up the admin server instance:

This will display a lot of output, starting with this line:

Starting Macromedia JRun 4 (Build 84683), admin server

(although your build number may be different) and ending with this line:

Server admin ready (startup time: 6 seconds)

Then the output will stop but you will not get your prompt back - don't worry, your Terminal is now running JRun4. Do not close that Terminal window! You can easily open a new Terminal window by pressing cmd-n (cmd - command - is the Apple key or, as some people call it, "splat") or selecting File > New Shell.

If you go to your browser and visit http://127.0.0.1:8000/ you should be greeted by the JMC login prompt.

Preparing To Install ColdFusion MX 7

Open a new Terminal window and go to your desktop (or wherever your browser downloaded the JAR file) and run the installer from the command line:

(or whatever the downloaded JAR file was called). It will start the Java installer and you will have to click the Terminal window again to make it active. Tell the installer you want the J2EE WAR version and tell it to install the files in /Users/{username}/Desktop/cf7 - note that the installer doesn't actually install anything, it really just unpacks some files. When it's done, have a look in the install directory and you should see cfusion.war, rds.war and several other files:

(remember that you were in the desktop directory so cd cf7 takes you to the subdirectory cf7 - use pwd to double-check where you are).

Creating The Server Instance For CFMX 7

You already started the JMC (the JRun admin server instance) above and you probably already logged in? If not, go and login. If the browser says there's no response on http://127.0.0.1:8000/ then you probably closed the Terminal window in which you started the admin server - in which case, open a new Terminal window and start the admin server as shown above.

Now you're going to create a new server instance and change the port number to something memorable.

Click the Create New Server link in the top navigation, enter cf7 in the JRun Server Name and press tab - it will automatically populate the JRun Server Directory (leave it as a default). Click the Create Server button. When the dialog refreshes, you can change the Web Server Port Number (to, say, 7000) and click the Update Port Numbers button. When it refreshes, click the Finish button.

Now we're going to tidy up the server directory before installing the CFMX 7 WAR files.

In a Terminal window, go to the JRun server directory and remove the default application directory:

You can double-check it worked by (a) running pwd and checking you are in the right directory and (b) running ls to ensure the only file remaining is the SERVER-INF directory.

Now you're going to create two directories to hold the WAR files.

In the same Terminal window, make sure you are in the /Applications/JRun4/servers/cf7 directory first and then create the directories:

Now you're going to install RDS:

It will unpack a few files. Double-check it worked by (a) running pwd to make sure you're in /Applications/JRun4/servers/cf7/CFIDE and (b) running ls to ensure the correct files are present (META-INF, WEB-INF and rds.properties).

Now you're going to install CFMX:

Make sure you are in the right directory before you run the jar command this time! Use pwd to check you are in /Applications/JRun4/servers/cf7/cfusion (the ../ in the cd command means go up one level first).

This will take some time as it unpacks a lot of files. Using ls afterward will show you CFIDE, META-INF and WEB-INF (and cfdocs I think) - this CFIDE directory is the ColdFusion Administrator (not to be confused with the previous CFIDE directory you created which holds the RDS application data).

Now you need to make a small modification to the JVM configuration in order for CFMX to run. The file is jvm.config and lives in JRun's bin directory. You need to add -Djava.awt.headless=true to the end of the java.args definition. Before you edit it, it will look like this:

java.args=-Xms32m -Xmx128m -Dsun.io.useCanonCaches=false

After you edit it, it should look like this:

java.args=-Xms32m -Xmx128m -Dsun.io.useCanonCaches=false -Djava.awt.headless=true

If you feel comfortable using vi (the Unix visual editor, sometimes known as vicious instrument), you can do the following:

If you would prefer to use a more familiar text editor, you can edit the file using TextEdit:

This will open TextEdit. Make the changes described above and save the file.

Starting your new CFMX 7 server

Just as the JMC admin server took over a Terminal window, so will CFMX 7. I'll explain below how to have this not happen.

After a short wait (30 seconds maybe) you should see a line like this:

Server cf7 ready (startup time: 27 seconds)

Now you can visit the ColdFusion Administrator and run the "first-time" wizard. If you followed these instructions exactly, this URL should work: 

http://127.0.0.1:7000/cfusion/CFIDE/administrator/

Walk through the one-time setup wizard and you're done!

Your ColdFusion document root (aka webroot) is:

/Applications/JRun4/servers/cf7/cfusion/

That's where your CFML pages should live. If you put an index.cfm file there, you can access it with this URL: 

http://127.0.0.1:7000/cfusion/index.cfm

Enjoy your new server!

Starting JRun and CFMX 7 in the background

As mentioned above, if you start up a JRun server instance in a Terminal window using the basic /Applications/JRun4/bin/jrun start servername command, it effectively takes over that window. I have a Unix shell script that starts server instances in the background and saves the console output to a log file. Here's what is in that script:

#!/bin/sh
JRUN_HOME="/Applications/JRun4"
LOG_HOME="${JRUN_HOME}/logs"
if test x$1 = x
then
	server=cf7
else
	server=$1
fi
cd ${JRUN_HOME}/bin
./jrun -start ${server} \
	1>$LOG_HOME/${server}-out.log 2>$LOG_HOME/${server}-err.log &

Don't despair at the seemingly complex syntax - you really don't need to understand it (and I'm not going to explain it)! You can download it as a ZIP file. I suggest you unzip this into your home directory (cd with no argument changes to your home directory):

This will create a file called cfmxstart in your home directory (if your default download location is not your desktop, you'll need the downloaded file to your desktop for the commands above to work!). Now, whenever you are in a Terminal window you can start up a server in the background like this:

That will start a server instance called cf7 by default. If you want to start a different server instance, specify the server instance name as an argument:

That will start the JMC (admin server instance).

Note that there is no output and you get your command prompt back immediately. The server starts up in the background and may take some time before it can handle requests. The log files that are created can be found in /Applications/JRun4/logs and, for the default case cf7, will be called cf7-out.log and cf7-err.log. You can open these in any text editor to what the server is up to (the log files contain what you would previously have seen in the Terminal window with regular informational output in *-out.log and errors in *-err.log).