Installation

Instructions for installing Wheels on your system.

Installing Wheels is so simple that there is barely a need for a chapter devoted to it. But we figured we'd better make one anyway in case anyone is specifically looking for a chapter about installation.

So, here are the simple steps you need to follow to get rolling on Wheels...

1. Download Wheels

You have 2 choices when downloading Wheels. You can either use the latest official release of Wheels, or you can take a walk on the wild side and go with the latest committed source code in our Subversion (SVN) repository.

The latest official release can be found in the downloads section of this website, and the SVN trunk is available at our Google Code site.

In most cases, we recommend going with the official release because it's well documented and has been through a lot of bug testing. Only if you're in desperate need of a feature that has not been released yet would we advise you to go with the version stored in the SVN trunk.

Let's assume you have downloaded the latest official release. (Really, you should go with this option.) You now have a .zip file saved somewhere on your computer. On to the next step...

2. Setup the Website

Getting an empty website running with Wheels installed is an easy process if you already know your way around IIS or Apache. Basically, you need to create a new website in your web server of choice and unzip the contents of the file into the root of it.

In case your not sure, here are the instructions for setting up an empty Wheels site that can be accessed when typing localhost in your browser. The instructions refer to a system running Windows Server 2003 and IIS, but you should be able to follow along and apply the instructions with minor modifications to your system. (See Requirements for a list of tested systems).

Create a new folder under your web root (usually C:\Inetpub\wwwroot) named wheels_site and unzip the Wheels .zip file into the root of it.
Create a new website using IIS called Wheels Site with localhost as the host header name and C:\Inetpub\wwwroot\mysite as the path to your home directory.

If you want to run a Wheels powered application from a subfolder in an existing website, this is entirely possible, but you may need to get a little creative with your URL rewrite rules if you want to get pretty URLs—it will only work out of the box on recent versions of Apache. (Read more about this in the URL Rewriting chapter.)

3. Setup the Database (Optional)

Create a new database in MySQL, Oracle, PostgreSQL, or Microsoft SQL Server and add a new data source for it in the ColdFusion/Railo Administrator, just as you'd normally do. Now open up config/settings.cfm and call set(dataSourceName="") with the name you chose for the data source.

If you don't want to be bothered by opening up a Wheels configuration file at all, there is a nice convention you can follow for the naming. Just name your data source with the same name as the folder you are running your website from (mysite in the example above), and Wheels will use that when you haven't set the dataSourceName variable using the set() function.

4. Test It

When you've followed the steps above, you can test your installation by typing http://localhost/ (or whatever you set as the host header name) in your web browser. You should get a page saying "Welcome to Wheels!"

That's it. You're done. This is where the fun begins!

« Previous Chapter
Requirements

^ Top
Table of Contents

Next Chapter »
Upgrading to Wheels 1.x

Comments

Read and submit questions, clarifications, and corrections about this chapter.

[Add Comment]

Hi,

I'll be brief,

1. successfully installed, tested CFWheels (Congratulations! page loads fine)
2. My URL: http://localhost:8500/wheels_site/
3. Hello World (or the Say.cfc) doesn't fly for me, despite following directions:
4. URL:  http://localhost:8500/wheels_site/say
5. Error: 404
                /wheels_site/say
                java.io.FileNotFoundException: /wheels_site/say
            ... etc ....

Can you help?

Thanks!

# Posted by Bryce | 9/3/2009

Bryce,

If you install in a subfolder ("wheels_site" in your example), then you forgo the ability to do URL rewriting.

So in order to get it working, you needs to call the say controller like so:
http://localhost:8500/wheels_site/index.cfm/say/hello

If that doesn't work, try this:
http://localhost:8500/wheels_site/index.cfm?controller=say&action=hello

# Posted by Chris Peters | 9/3/2009

I figure I am being a bit dense, but I wondered if I could get a bit of clarification on the two steps you discuss to creating a new cf_wheels website.

On the first, I understand I should create a directory under wwwroot called wheels_site, but should I put all of the contents of the cfwheels.0.9.4 zip file in it, or just the contents of the zip's wheels folder?

On the second, I am not clear on what you mean by creating a new website and setting the host header name. I am running IIS 5.1 on Windows XP (development box). Also, it seems that the directory you mention "\Inetpub\wwwroot\mysite" should have some contents. It doesn't mention putting anything in the folder. Should it have the folders in the zip file except for the wheels folder?

Thanks for your help.

# Posted by Tom | 10/8/2009

I am looking to do a CFWheels demo for our User Group next month. I created a IIS site on Windows 7 and created a hosts to see the site as "http://cfwheels". Put an index.cfm file in the folder and verified it was working. Removed the file and unzip'd your file into the folder.

Didn't work right? (What did I miss?)

Here is the error. (Note if I got this working without the CFWheels files.)
HTTP Error 500.19 - Internal Server Error
The requested page cannot be accessed because the related configuration data for the page is invalid.

# Posted by John Farrar | 12/17/2009

I figured it out. You had a file in the download called "web.config" and that was causing the error in my scenario. Not sure if changing or removing that effects things but it did start running.

# Posted by John Farrar | 12/17/2009