There are several installation options for the latest version of FarCry (5.0.2) which makes things nice and flexible for the framework to be used by different people in a variety of setups.
The deployment configurations page has some easy to follow instructions for installing in “Standalone” mode. This is really the best option if you are in a shared environment where you may not have control over ColdFusion mappings, but also if you are looking to get up and running quickly (maybe you just want to evaluate the product etc).
For us we use FarCry for many applications, but in what would be considered an “Advanced” configuration mode (using FarCry 5+ parlance). Unfortunately it looks as though we may stray a little from the “Advanced” configuration which is the point of this tutorial.
The current advanced setup may be a little confusing to some. It doesn’t really list full details for the advanced mode, but still seems to require you to have FarCry running in the following directory structure (note that in the example below ‘farcry_5.0.2’ can really be called anything and is not a strict naming requirement, I like to use this as it is explicit as to which version I’m using):
- /farcry_5.0.2
- /core
- /plugins
- /farcrycms
- /projects
- /myproject1
- /myproject2
- /skeletons
- /mollio
This is nice and easy as it gives you the ability to have only 1 ColdFusion mapping (/farcry pointing to your /farcry_5.0.2 directory) which all your projects can share (i.e. all projects would share the same farcry “core” and “plugins” codebase etc). It’s this structure where our setup starts to differ.
We typically have library directories to hold shared codebases and a completely separate location for our vhosts (projects or “web sites”). This is the main difference and means we have something like the following:
- /libs/farcry_5.0.2
- /core
- /plugins
- /farcrycms
- /projects (note this is only needed for our installation, we won’t be hosting projects from here)
- /skeletons (note this is only needed for our installation, we won’t need this in production)
- /vhosts
- /myproject1
Note: In actual fact our vhost setup is slightly different than what I’ve listed above, but this is easier to describe for the purposes of a tutorial.
This is an extremely flexible setup, but installing this way is a little tricky. I’ve done several installs for this configuration using the following steps:
Installation - Preparation
Is is assumed that your farcry files, as mentioned above, are in the following location (this location is of course an example of what you may have on a linux based machine, you could obviously use a different path like C:/libs/farcry_5.0.2):
- /libs/farcry_5.0.2
It is also assumed that you want to install your project into the following location:
- /vhosts/myproject
*Note: DO NOT actually create this project folder yet, we will move the folder to this location after the FarCry installation has completed.
Follow the following steps:
- Create a blank database. This can be called anything you want, typically something which mirrors your project name is a good idea
- Create a new datasource in ColdFusion Administrator and verify that it is connecting to your new database
- Create your project vhost (i.e. http://myproject.local) in your web server of choice (Apache or IIS etc)
- Point the document root to ‘/vhosts/myproject/www’ (even though this actual location doesn’t exist yet!)
- Make sure you have a ‘/webtop’ alias (this replaces the old ‘farcry’ alias for those familiar with prior versions of FarCry) pointing to /libs/farcry_5.0.2/core/webtop
- Create an entry in your hosts file so myproject.local is in use on 127.0.0.1 (for production you’d obviously use different settings!)
- Create a ‘/farcry’ ColdFusion mapping pointing to the directory which holds “core” (i.e. /libs/farcry_5.0.2)
- Create a ‘/farcry/projects/myproject’ ColdFusion mapping
- mapping: /farcry/projects/myproject
- path: /vhosts/myproject
*Note: You could get away with having a single ColdFusion mapping of /farcry/projects if all your projects existed under the same directory (i.e. /vhosts), otherwise create a projects mapping per project (e.g. /farcry/projects/myproject). I find it’s a good idea anyway to have a separate mapping per project.
Installation - Installing
To install FarCry we visit the ‘/webtop/install’ sub-directory off your project URL, e.g. http://myproject.local/webtop/install/.
You may be wondering how this works as we haven’t setup our physical project diretory yet, it works because of the web mapping (alias/virtual directory) of ‘/webtop’ which points directly to /farcry_5.0.2/core/webtop/install.
Ok we’re almost there! If everything is going well so far and the stars have aligned you’ll see the FarCry installation screen.
The important value on this page is “Project Folder Name”. This should be “myproject” (i.e. what will become the physical name of your project directory, the same name as we added in our vhost).
The 2nd step allows you to enter your ColdFusion datasource and database type:
On the 3rd step you must choose a skeleton to install from. Just use the default ‘mollio’:
The 4th step is for plugins, for most cases leave the default which is probably ‘farcry’ and ‘farcry greybox’:
The 5th step is important as the default is “Sub-Directory”. You have to change this to the last option “Advanced Configuration”:
Step 6 is a confirmation step, nothing to do here except “INSTALL NOW”:
After hitting “INSTALL NOW” FarCry will go off and do its magic:
When the installation is complete and you can see the final screen FarCry will have successfully installed your project under the /libs/farcry_5.0.2/projects/myproject directory.
*Important* BEFORE you click the “VIEW SITE” or “LOGIN TO FARCY WEBTOP” buttons you must move the project directory to where you’ve specified in your vhost (i.e. move ‘myproject’ from ‘farcry_5.0.2/projects/myproject’ to ‘/vhosts/myproject’).
Once you’ve moved your project directory, you can click the “Visit Site” button and/or “Login to the FarCry Webtop” and you’re ready to roll :)
Hopefully that helps people trying to install FarCry in a slightly different configuration.