How Do I Install Mach II? - Mach-II/Mach-II-Framework GitHub Wiki

Table of Contents

1. Watch a Screencast
2. Railo
3. Installing the Core Framework
   • Instructions
   • New Users Notice
   • Upgrading Note
   • If you encounter problems
4. Installing the Skeleton App
   • If you encounter problems

Watch a Screencast

Watching somebody do it is worth a thousand words. Just see how dead simple it is to install Mach-II and the application skeleton with Brian FitzGerald:

Mach-II Installation from Brian FitzGerald on Vimeo.

Railo

For developers that use Railo, you can use the Railo Extension Provider that is maintained by Lamoree Software. They offer the latest stable in addition to the nightly / BER via the Extension Provider. To install Mach-II using the Extension Provider, please visit Lamoree Software:

http://railo.lamoree.com/

Installing the Core Framework

Instructions

1. Download the core framework code from GitHub or The current stable version from here.
2. Unzip the framework core to your web root.
   1. For example, on Windows the default web root is [DRIVE]:\\Inetpub\\wwwroot, or if you are using your CFML engine's built-in web server, your web root could be something like [DRIVE]:\\CFusionMX\\wwwroot. If you are on a Unix system, your web root will vary.
   2. The end result of this step is that you should have the directory MachII (no hyphen) in your web root. Inside this directory you will find the core framework files.
   3. If you wish to place the core Mach-II framework files in a location that is different from your webroot, just create a mapping called "MachII" in your !CFML engine's administrator that points this mapping to the location where you placed the framework files. See I cannot use server-wide mappings or place Mach-II in my webroot, how can I extend MachII.mach-ii in my Application.cfc? for additional options.
3. If you use sandbox security on your CFML engine, you may have to add the framework's directory to your sandbox otherwise your CFML engine may throw an java security exception.

Just three simple steps and you are done. The Mach-II framework is just another CFML application, so it will operate and behave just like any other CFML application. Please read the Upgrading Note below if you are upgrading your installation of Mach-II.

Mach-II uses absolute pathing for CFCs, so installation of both core framework files (the MachII directory).

If your webroot is "wwwroot", your directory structure should look like this:

|-+ wwwroot
  |- MachII
  |- MyCoolApplication
  |- MyBlogApplication

New Users Notice

The framework core is not a stand-alone application. Do not expect to run the mach-ii.cfm and expect a "welcome" message. Download the Mach-II Skeleton available at mach-ii.com to start a new application or download a sample application.

Upgrading Note

If you are updating your Mach-II installation from an older version, you must clear your template cache and restart your CFML engine after you replace your older version with a newer version.

If you do not clear your template cache and restart your server, you will receive an error similar such as:

• The value returned from function getAppFactory() is not of type MachII.framework.AppFactory.
• Element AppLoader undefined in application[MACHII_APP_KEY].

If you encounter problems

1. Please first ensure that your directory structure matches the one shown aboveor that your "MachII" mapping is pointing to the right directory if you are using a mapping.
2. Clear your template cache if you have caching on and restart your CFML engine service.
3. Check these upgrading FAQs:

• Help! I am getting errors when I upgraded my install of Mach-II. What are the common problems?
• I'm upgrading from an earlier version of Mach-II to a newer version. Am I going to have any problems?
• What elements have been officially deprecated in Mach-II?

1. If problems persist, please check out the Mach-II for CFML Google Group: http://groups.google.com/group/mach-ii-for-coldfusion

Installing the Skeleton App

1. Download the core framework code from http://www.mach-ii.com and follow the instructions in the README file to install the core framework code. Please Note Well: The framework core is not a stand-alone application. Do not expect to run the mach-ii.cfm or any other .cfm file and expect a "welcome" message.

2. Download the Mach-II Skeleton available at mach-ii.com to start a new application or download a sample application.

3. Unzip the framework to your web root or sub directory. Make note of where you unzipped the skeleton as it's important in the next step.

4. Depending where you unzipped the skeleton, you need to make one change to the mach-ii.xml configuration file. In the [path]/config/mach-ii.cfm in the skeleton you just unzipped, look for the follow line of code: <property name="applicationRoot" value="/CHANGEME" />

   1. If you unzipped the skeleton in the webroot, then change the value of "/CHANGEME" to "/".
   2. If you unzipped the the skeleton in a sub-directory of your webroot, then change the value of "/CHANGEME" to "/[path]" where [path] is the directory off your webroot. For example, if you put the skeleton in a directory called "/myapp" (i.e. http://localhost/myapp) then the value should be "/myapp".

5. You're done! It was that simple. Test your core Mach-II framework and ColdSpring by calling the showHome event (http://server[/path]/index.cfm?event=showHome), which will display a page giving you basic feedback on whether or not Mach-II and ColdSpring are configured correctly.

If you encounter problems

1. Please first ensure that your applicationRoot property value was changed to the correct path for where you unzipped the skeleton.
2. Clear your template cache if you have caching on and restart your CFML server service.
3. If your problems persist, please check out the Mach-II for CFML Google Group