Railo 3.0 Community, Resin 3.1 and IIS6 -- Learn from my mistakes
Posted by Jason Durham | Tags: ColdFusion , IIS , Railo
I've been hearing lots of great things about Railo from the ColdFusion community. I was also delighted to see that Coldbox and Transfer ORM work on Railo 3.0 Community. I don't see Coldspring on the Railo web site, but Google indicates I might be in luck.
The documentation on Railo's web site leaves much to be desired. Their installation documentation page tells you to view the "Readme.txt" included in the download. When you open the "Readme.txt", you see this...
You find a detailed installtion documentation on: http://www.caucho.com/resin-3.0/install/httpd.xtp
Wow... that was a lot of help. :o) Also, I sent in two support requests yesterday, neither of which have been replied to yet. I'm beginning to feel that "you get what you pay for." In case there are other people out there who don't know the basics of how Railo works, here are a few key things that I wish Railo displayed prominently in a "Getting Started" part of their web site.
When you get to the "Downloads" part of their site, you will see "Railo Express" and "Railo Server". Neither of which say Community edition. I thought I'd start with "Express" since it seemed to follow the same naming convention as MS SQL's free database. Their site says to unpack the archive, download JDK (isn't it SDK now?), bolt up to the JRE, click here, click there... and whaabamm... you're parsing CFML pages. This was not the case for me. I chased my tail for an hour before I decided that perhaps I was having problems with Java. I downloaded the Railo Express version including JRE and still had no luck. Probably 2-3 hours had passed looking for documentation, trying different things... my patience was wearing thin.
While cruising Railo's site, I realized that Railo Community edition is actually Railo Server. Perhaps I was foolish to start with Railo Express but maybe adding the word "Community" somewhere on the download page would prevent other foolish people from making a mistake and wasting 1/4 of their day on it. So, I downloaded Railo Server, ran setup.exe and I was off and running. Also, it seems that you must register on Railo's web site as a "new customer" and "purchase" a $0 Community edition license. Some of this information would have been great content for a "Getting Started" guide for Railo.
With Railo (and Resin) installed now, I could access http://localhost:8600 and see a series of <cfdump>s indicating I was good to go. However, Railo still needed to be configured for IIS. Here is what I did to get it to (kinda) work...
- Create a folder within inetpub called "scripts"
- Create a virtual directory in your IIS web site pointing to the scripts folder created previously (added 12/31, fixed routing issue).
- Execute "setup.exe" from the installation directory of Railo. Enter the path to the scripts folder in the "IIS/PWS" field. Isapi_srun.dll should now appear in the scripts folder.
- Create web service extension in IIS for .cfm and .cfc files and point them to the Isapi_srun.dll created previously.
- Add index.cfm to default template list.
- Be sure that Home Directory > Application Settings > Execute Permissions is set to "Scripts and Executables"
- Open the Railo installation directory and locate conf/resin.conf. Open it in your favorite XML editor and now it's time to roll up your sleeves.
Resin has pretty specific instructions on how to configure itself to work with IIS. I won't regurgitate it here. The basic idea is to point the "default document directory" to your IIS web root and create an XML node for each virtual site/host. Here is a basic sample of both of these...
<cluster id="app-tier">
...
<!-- configure IIS sites routing by host -->
<host id="mydomain.com" root-directory=".">
<host-alias>www.mydomain.com</host-alias>
<web-app id="/" document-directory="e:/inetpub/wwwroot/myWebSite"/>
</host>
<!-- configures the default host, matching any host name -->
<host id="" root-directory=".">
<!--
- configures an explicit root web-app matching the
- webapp's ROOT
-->
<web-app id="/">
<document-directory>e:/inetpub/wwwroot</document-directory>
</web-app>
...
</host>
</cluster>
....
At this point, if I haven't forgotten anything, you should be ready to call .CFM/CFC templates from your default IIS directory. If anybody is using this as a guide and doesn't find this to be true, please let me know and I'll figure out what I left out and help you get through it.
Here's the catch.
The machine I'm using to test Railo is our Intranet server. It's a Windows 2K3 Server that has never done anything other than serve static pages. Our employees are accustomed to typing "intranet" (no extension) in their browser and having the default document load. In IIS, we simply routed by the host header and voila, default.htm loaded every time. However, this does not work for dynamic pages with Railo/Resin. If I try to access http://intranet/index.cfm, I get a 404 error returned from IIS. If I make a few configuration changes and add .foo to the host, index.cfm loads like a champ (ie. http://intranet.foo/index.cfm). I'm not sure if this is because I missed something configuring Railo/Resin or if it's a limitation of the Resin/IIS integration. I've got an email floating around on Resin's list hoping to identify the problem.
In summary...
While I'm very grateful the guys/gals at Railo have provided us a robust CFML engine, I'm very disappointed in the documentation. I think it would behoove them to create a "Getting Started" document that gives the user a high level understanding of what to expect with Railo. With Railo... you get Resin... with Resin... you get a web server. For it to work 'out of the box', you're going to have to spend some time learning new things. The installation and configuration is nowhere near as simple as Adobe ColdFusion. I think users should be prepared for that.
UPDATE: Routing issue solved! - 12/31/08
Somehow I missed something important on Resin's instructions for configuring IIS6. You must create a virtual directory in each CFML web site pointing to the "scripts" folder (see list above). Now it's time to move some previously written apps to Railo and see how they work. :)
4 responses so far ↓
Leave a Comment