[[Dashboard| << Back to Dashboard]]

{|align="right"
|-
| __TOC__
|}

[[Category:setup]]

= Installation Guide =

{{{Messagebox message="Covers up to version 3.1.0" type="info"}}}

== Introduction ==

There are several ways to install ColdBox for different environments, and you are encouraged to try them out.  However, this guide lays out the supported installation configurations.  Please also see the [[Refactoring | Refactoring Guide]] for embedded or custom installations for environments that required more than a single server.

== Main Requirements ==
 
=== CFML Engines ===
* [http://www.adobe.com/products/ColdFusion/ Adobe ColdFusion] MX 8.X and above (7.X is supported by ColdBox 3.1.0 & below).
* [http://www.newatlanta.com/products/bluedragon/index.cfm BlueDragon 7.X] and above.
* [http://www.railo.ch/en/ Railo 2.0] and above

{{{Messagebox message="CF7 compatibility will be dropped in ColdBox 3.5.0 and beyond." type="warning"}}}

=== CF Specific ===  
* Application scope must be enabled for framework operations
* Requires the ability to create components and Java objects using CreateObject()

=== OS ===
* Windows, Mac OS X, Unix/Linux


== Typical Installation ==

Once you [http://www.coldbox.org/download | download] the ColdBox distribution bundle you can place it on your web server root, the root of your virtual host, or the root of whatever website you have mapped in your favorite web server software:

<pre>
{Web_Root}/coldbox/
</pre>

You can now point your browser to the ''samples'' directory to view the samples gallery or look at the ''ApplicationTemplates'' folder to start a new application.  The install folder contains several files that will help you get started.

<pre>
http://localhost/coldbox/samples
http://localhost/coldbox/ApplicationTemplates
</pre>

{{{Messagebox message="For production servers, please leave only the <b>system</b> folder. You can remove the rest of the directories." type="info"}}}
{{{Messagebox message="For development servers, make sure <strong>REPORT EXECUTION TIMES</strong> on the CF administrator is turned off so speed can improve <b>considerably.</b>" type="info"}}}

== Alternate Installation Methods ==

There are more ways in which you can install ColdBox.

{{{Messagebox message="You can find a <em>refactor.xml</em> 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." type="info"}}}

=== ColdFusion Mapping ===

ColdBox can also be installed by creating a ''/coldbox'' mapping in your ColdFusion server administrator or in your per-application mappings.  Please also note that the application templates have two ''Application.cfc'' files, one with inheritance and another without inheritance, so you can use per-application mappings in the '''non-inheritance''' approach.  You can read more about it in our [[Bootstrapper]] section.

=== 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_latest''. 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 and is named: ''refactor.xml.''  Make sure you change the system_path, basedir, and destination properties to meet your needs. Please read the [[Refactoring | Refactoring Guide]] for an in-depth guide on refactoring the code base.

== Upgrading ColdBox ==

Updating a ColdBox install to a new version is as simple as pie.  You only need to make a backup of the original ''coldbox'' directory (optional) and then just place the new expanded archive in the original location.  Once you've replaced the files, please make sure to read the appropriate compatibility guides and release notes.

<div class="mynotes">
<strong>Important:</strong> If an upgrade is done, make sure you reinitialize your applications since they still have old code in memory. A ColdFusion server restart is recommended.
</div>

You can do this by invoking the '''fwreinit=true''' [[URLActions | URL action]] or just removing the controller from application scope and recreating it. It is recommend that you bounce your CF server, so you know that you will start fresh.