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 Git repository is available at our GitHub repo.
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, Microsoft SQL Server, or H2 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!
Comments
Read and submit questions, clarifications, and corrections about this chapter.
ColdFusion hosting provided by
Vivio Technologies.
© 2012 ColdFusion on Wheels
Wheels is licensed under the Apache License, Version 2.0.
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!
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
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.
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.
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.
I was having issues getting my site to work until I realized that unlike other frameworks (Mach-II, Model-Glue, etc) your source code will live inside the unzipped cfwheels directory, not at the same level with a mapping to it. I was very confused by the instructions that said to unzip cfwheels into a directory in your workspace called wheels_site, and then to create an IIS site that points to a different directory called mysite. All you need to do is create a folder in your workspace, unzip cfwheels into it, and point IIS at that site and you're up and running. All of your code will actually go into the directories provided to you by wheels, which is pretty handy.
I hope this helps others who were tripped up by the same thing.
I downloaded wheels and installed in a sys folder at the root level, test worked fine. But when I tried to install at the root (not within a folder) I get a java.string error that refers to: #application.wheels.dispatch.$request()#
Anyone else encounter this issue?
I have tried installing this with Railo and tomcat, I put it in the webapps/ROOT/ folder at wheels_site, but when I go to localhost/wheels_site I get:
Wheels.ViewNotFound
Could not find the view page for the index action in the Wheels_site controller.
What else do I need to do to get this to work, I am not sure about this, there seems to be a lot of posts about 'url rewriting' which I don't know much about also.
Please help me.
"Installing Wheels is so simple that there is barely a need for a chapter devoted to it."
I think that this is hardly the case. This document only really addresses a Windows-based server installation; I am trying to get this running on Tomcat with Railo (setup using a WAR file), and have not been able to do it.
Every time I try to access my application (which would then be http://www.mywebsite.com/railo/, since the WAR created a sub-directory for the application), it thinks that the /railo/ is a controller, rather than the root.
I know that this is not really an issue with this software, but rather Tomcat and URL rewriting, but here, no anywhere else on the net, have I found any solutions to this (as well as my own experimentation)...
Thanks John Farrar, I had the same issue. Deleting the web.config file fixed it.
How do I get the installation working without deleting web.config??