Install Guide

Introduction

Welcome to the ColdBox installation guide. There are several different environments and ways to install ColdBox. I encourage you to try several different ways. However, below I lay out the supported installation configurations. Please also see the Refactoring Guide for refactoring ColdBox for embedding it in applications or custom installations, if you do not want a single server installation.

Typical Installation

Once you download the ColdBox distribution bundle you can place it on your web server root or in the root of your virtual host or the root of whatever website you have mapped in your favorite web server software:

• {Web_Root}/coldbox/

You will have the following once the archive is expanded:

| 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 and cfcviewer plugin's css can be overrided and then you would not have to worry about this anymore.

Refactoring: Embedded or Custom Mapping

You can refactor the entire ColdBox codebase in order to embedd it in your application or create a custom mapping or installation location. 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 it manually or 10 seconds with the included ANT task.

The ANT task 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 on refactoring the code base. For manual refactoring follow the instructions below:

• 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.

Now, this is a lot of work, so I would recommend you take 15 minutes to learn a little a bit about ANT and use the refactor.xml to refactor the entire codebase to whatever you need in less than 10 seconds.