One of my unwritten goals (plenty was written) for 2009 was to master a new CFML framework. I've used Fusebox and Model-Glue 2 (Unity) over the years but wanted to see what else was out there. After researching a variety of CFML frameworks, I selected ColdBox over cfWheels, Model-Glue 3, and Mach-ii.

Why ColdBox?
Let me say, from the outset, that my selection is in no way a reflection on cfWheels, Model-Glue 3, and Mach-ii. All are excellent and I love the fact that I was struggling to select one amongst all the CFML framework options. It's great to have so many excellent choices in our little community!

ColdBox's selection came down to 4 key elements for me:
  1. Convention over Configuration—ColdBox is not alone here but implementing this philosophy was central to my search. The more I work on team projects, the more I appreciate what this approach brings.
  2. Standard Web or Remote Access—The same ColdBox application can be used with any type of front-end: HTML, Flex/Flash, AIR, or Ajax interfaces.
  3. Toolkit over Framework—ColdBox bills itself as more than a framework, noting that it 'introduces several software application aspects that will help you build your applications faster, debug with ease and much much more.' (TransferORM, ColdSpring, etc.)
  4. Documentation—The ColdBox team has done an awesome job building a beefy set of documentation for the framework.

ColdBox Series
I spent some time over the last month reading the ColdBox documentation, playing with some tutorials, and trying a few features of the framework. While that was incredibly helpful getting my head around ColdBox, I always prefer meaningful or realistic tutorials that show me not only the basics of a framework (or language) but also how I would actually use it on a site.

I decided to keep a running set of posts on ColdBox for this purpose; develop a detailed, hopefully, real-world applicable tutorial. How? Well, I'm actually using ColdBox (and recording it in this series) to rebuild my original company site (

While ImageAid is still my official business entity, I'm transitioning to a new identity for my development work. My wife, however, is an editor and continues to use ImageAid for her business. So, it's really her site :). In part two of this series, I'll outline what features I want to implement on the site, how ColdBox will figure into the plans, etc.

For now, let's get started and install ColdBox!

Development Environment
I am developing on a Mac (10.5.7) with Apache 2.2.9, MySQL 5.0.67, and ColdFusion 8.0.1. I also test and develop against an Apache (2.2.9), Tomcat 6.0.18 and Railo 3.1 (beta) setup on the same machine. Okay, I really do it all on the Tomcat/Railo server and then test on CF8 to ensure it works. What can I say, I love open-source :)!

All that said, everything we're doing should work on Windows and other 'nix variants (system paths notwithstanding), so long as you have either CF8 or Railo 3.1 installed and running.

My IDE is Aptana Studio (Andretti Alpha version), which I love. Aptana is based on Eclipse for those unfamiliar with it (ala Adobe Flex Builder). Naturally, I have the CFEclipse plug-in installed for CFML editing.

Framework Installation
As with most CFML frameworks, installation is easy.

  1. Download—I selected the 2.6.3 bundle, which is 5.2 MB.
  2. Unpack—Once the bundle is downloaded, unpack it.
  3. Rename—Once the bundle is unpacked, rename the resulting folder to 'coldbox'.
  4. Move—Copy or move this folder to your web root folder.
  5. Mapping—If desired, set a mapping in the CF Administrator, called 'coldbox' and point to your coldbox directory now in your web root folder (this step is optional, but advised).

Application Skeleton
Open the coldbox folder in your web root. You will see a subfolder called 'ApplicationTemplate'. This is important to note because it's the base application structure you need to run a ColdBox application.

You can create a new ColdBox application in one of two ways: (1) copy the contents of this folder to your site/app's directory or (2) run an Ant script to do it for you.

For now, we'll use option 1, copying it manually. I you're interested in the Ant approach, check out the ColdBox documentation on My First Application. Yes, part one of my series is very much akin to this tutorial but will deviate (original content) in the subsequent posts!

Create a ColdBox Application
  1. Create a new folder in your web root and name it: cb_learning
  2. Copy the contents of the ApplicationTemplate directory (above) to this folder.
  3. From the cb_learning directory (or whatever you named it in step 1, above), open config/coldbox.xml.cfm in your editor and add a custom name for your application on line 6 (XML element = Setting name='AppName' value='custom_name_here')
  4. Go to http://localhost/cb_learning/ to see the ColdBox skeleton.*

That's it. You should now be running a skeleton ColdBox application!

The next post in the series involves getting comfortable moving around the framework and customizing the views/layouts. I'll also note the features I'll be adding to the real site ( I'm developing alongside this series.

*Your URL may vary depending on how CF is configured on your server.


Craig Kaminsky
@Anonymous - I'm afraid I cannot help here. ColdBox has changed significantly since this was posted and I am no longer writing ColdFusion apps. Apologies for the inconvenience.
config/coldbox.xml.cfm i am not getting this file under config folder?
Craig Kaminsky
Thanks Jose. I'll be getting back on the blogging horse next week. I broke my wrist on May 18 and it was a bit too much to keep coding/working with one hand and blogging! But the cast comes off next week and I should be back to real typing then :).

In the meantime, I'd be happy to help you with your Mac setup. I played around with mine for 2 years before I was happy but now I love it!

Send me an email (craig.kaminsky at gmail dot com) and I'd be happy to help. You'll love having CF integrated into your Apache install!!

Oh, I do have a couple of posts on this (check the labels for Apache and Tomcat).
Jose Galdamez
I'm definitely going to have to follow your progress as you move along in learning ColdBox. I watched an introductory presentation on it at last year's CF United. I lost track of what was going on about halfway through cause I kept running into terms I had no clue about. I've made some progress since then, but I haven't made the time to pick up ColdBox and start from the basics. I think reading your posts will help me when I make the initial transition fairly soon.

I am currently intrigued by how you've got your set up going. I too run on a Mac at home. My current speed bump will be setting up the dev environment correctly. Sure, I could take the easy way out, install CF8 and use its built-in web server, which is how I've always done it in the past. What I really need to do, though, is get on the ball, learn how to set up Apache and make it flexible enough so that if I wanted to set up other servers such as Railo or PHP I could do it all from the same code base (like you've managed to do).

A lot of this stuff is still new to me (I had to google "Tomcat" to remind myself what it was *bows head down*). It'll take some time, but I'm definitely looking forward to what I'll be learning in the coming months.

Craig Kaminsky
Wow! That may be the first and last time I am at the top of Google!! Working on integrating BlazeDS into my Tomcat install...then, connect to Railo/Flex apps. Ugh, my head hurts from all this :)
Haha, I just found your article just before I saw your response to my comment. Incidentally, if you google "railo tomcat mac", your article comes up first in the results! I'm gonna check it out now! Thanks!
Craig Kaminsky
Thanks, Greg! I've got an entry from a bit back on Railo/Tomcat/Apache:

It has links to better-written articles on Tomcat/Railo where necessary but let me know if it doesn't help or get you enough details.

The 'best' part right now is that I can run and test CF8 and Railo 3.1 side-by-side, from the same code base. Apache Virtual Hosts, with custom domains ( for Railo and for CF were the key :).
Great article. I'd be interested to know how you set up tomcat/railo on the mac. Especially since you are able to boil things down into an easy-to-digest step-by-step process.