Install Guide

  1. Install Guide
    1. Introduction
    2. Typical Installation
    3. Alternate Installation Methods
      1. ColdFusion Mapping
      2. Virtual Directory or Apache Alias
      3. *nix Symbolic Links
      4. Creating another named mapping

Introduction

As of version 1.1.0 you will have only one installation of ColdBox per web server. Please look below for a structure of the bundle you download. Please also see the Refactoring Guide for refactoring ColdBox for embedding it in applications or custom installations.

Typical Installation

Once you download the ColdBox distribution bundle you can place it on your web server root:

  • {Web_Root}/coldbox/

You will have the following once the archive is expanded if you downloaded the bundle: 

| coldbox
|---+ ApplicationTemplate
|---+ dashboard
|---+ install
|---+ samples
|---+ system

You can now point your browser to the samples directory to view the samples gallery or look at the ApplicationTemplate folder to start a new application. The install folder contains several files that will help you get started and most importantly it contains the ColdBox Apache 2 License. The ColdBox Dashboard is a separate entity from the framework and is not open-source. It is under a completely different license. See License Agreement, FAQ

Note: For production servers, please leave only the system folder. You can remove the rest of the directories.

Note: For development servers, make sure REPORT EXECUTION TIMES on the CF administrator is turned off so speed can improve considerably.

Alternate Installation Methods

There are more ways in which you can install ColdBox.

Note: You can find a refactor.xml ANT task in the install folder that will be able to refactor the entire ColdBox source base to another mapping or path if you so desire.

ColdFusion Mapping

ColdBox can also be installed by creating a /coldbox mapping in your coldfusion server administrator. However, you must know that NO visual plugins (messagebox,cfcviewer) will show their images, because they have a mapping of /coldbox/system/includes/images. So if you are not using any of the visual plugins (messagebox,cfcviewer), then don't worry, this is the install for you. As a side note, the messagebox plugin's css can be overrided and then you would not have to worry about this anymore.

Virtual Directory or Apache Alias

You can also place the coldbox bundle directory somewhere in your server, lets say you place it in c:\frameworks\coldbox_2_0_0. Then you can create a virtual directory in IIS in the website that you want to have access to the framework. You would create a virtual directory called: coldbox that will point to c:\frameworks\coldbox_2_0_0.

If you are using apache, then you would create an alias with the name coldbox and the directory to c:\frameworks\coldbox_2_0_0. However, there is an important note when using the virtual directory or alias as shown below:

Important Note: If you follow this method, then please note that on ColdFusion 8 and BlueDragon 7, the multi-threaded capabilities will FAIL because they will not be able to find or use the apache alias or IIS virtual paths. So this installation method MUST be used in conjunction with a ColdFusion mapping as mentioned above.

If your server is a *unix server, then you are blessed by symbolic links, which have the same effect as a coldfusion mapping. You would have to create a symbolic link to the coldbox install directory from your document root.

Example: The document root for my site luismajano.com is /data/webroots/luismajano_com/ This is where all the files are and where the domain points to. Then I place my coldbox bundle file at /data/frameworks/coldbox_2_0_0. Then I would create a symbolic link at /data/webroots/luismajano_com/. Look at the code below: 

$>cd /data/webroots/luismajano_com/
$>ln -s /data/frameworks/coldbox_2_0_0 coldbox

This will create a symbolic link named: coldbox in my web root.

Creating another named mapping

You can also create a mapping with another name like coldbox_2_0. However, you will have to alter some of the core files for this, since ColdBox was designed for one server install. Don't panic, this is no big deal. It will take you about 10 minutes to do. How do I know. Well, I have done this before.

Now you can use the included ANT TASK to do this. It is in the install folder named: refactor.xml. Make sure you change the system_path, basedir and destination properties to meet your needs. Please read the Refactoring Guide for an in depth guide.

  • Change all the extends in the core and your components to match the named mapping.
    Example: coldbox_2_0.system.eventhandler

  • Change all the absolute mappings to the /coldbox directory. Look in the section above for the visual aspects. Below are the files you need to change in the core files for absolute mappings:
    • coldbox/system/plugins/XMLParser.cfc
      Change the instance.FrameworkConfigFile and the instance.FrameworkConfigXSDFile properties to point to the named mapping you choose.

  • Change all the return types and object references that start with: coldbox.system. to myname.system.

That is it. A little bit of more work for you guys, but if you need this control, then you can still do it with ColdBox.

Copyright 2006 ColdBox Framework by Luis Majano