Railo 3.1 on Windows Server 2008 and IIS7

This is the third of three posts on installing Railo 3.1 on Windows Server 2008 with IIS7. The previous post can be found here.

Okay, in our last episode, we focused our incredible shrinking brains solely on getting Tomcat and Railo set up and working as a standalone entity. We also did the preliminary work of getting IIS7 set up with whatever domains we plan on giving the ability to execute CFML requests. In this final chapter we are now going to do the dirty work of bridging the two together. As a reminder, here is my view of how the two entities (IIS and Tomcat) will be communicating:

rails tomcat and iss working together

The key to this bridge is "The Connector", a DLL whose job in life is to evaluate incoming http requests and determine if said request should be redirected for processing or not. I use the word redirected, but it isn't a true redirection in the sense of sending the caller to a different URL. Rather, it is more so deferred processing; if the incoming request matches a pre-defined filter list, then that request will be deferred to Tomcat for processing, the resulting html being returned to IIS for delivery to the caller.

Here's an overview of what we're going to accomplish:

acquire and install the DLL;
"wire up" the DLL to IIS7;
tell the DLL what requests to be watching for;
tell Tomcat what domains it should care about and where it can find those domains' content;

Before we begin, go ahead and make sure Tomcat is shut down. If you need to know how, see step 6 in the previous post.

Get The DLL
1. Download the DLL from http://www.ip97.com/apache.org/tomcat/tomcat-connectors/jk/binaries/win32/jk-1.2.28/isapi_redirect-1.2.28.dll . If that specific file is removed or superceded by a later version, or you find that you need the win64 version, just pare the url back to the appropriate place so you can drill down yourself.

2. Once you have the DLL, create a folder called 'scripts' under your inetpub folder and drop the dll in there.

3. Now we have to create the configuration files (.properties files) that the DLL will use to communicate with Tomcat. When you create these, make sure that a ".txt" extension doesn't get tacked on to the end, k?
a. Create C:\inetpub\scripts\isapi_redirect-1.2.28.properties
b. Paste the following into that file:

# Configuration file for the Jakarta ISAPI Redirector
# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/jakarta/isapi_redirect-1.2.28.dll
# Full path to the log file for the ISAPI Redirector
log_file= C:\Program Files\Tomcat6\logs\isapi_redirect.log
# Log level (debug, info, warn, error or trace)
log_level=debug
# Full path to the workers.properties file
worker_file= C:\Program Files\Tomcat6\conf\workers.properties
# Full path to the uriworkermap.properties file
worker_mount_file= C:\Program Files\Tomcat6\conf\uriworkermap.properties
#rewrite_rule_file= C:\Program Files\Tomcat6\conf\rewrites.properties
##########################################################

c. Create C:\Program Files\Tomcat6\conf\uriworkermap.properties and paste the following into it:

# uriworkermap.properties - for use with IIS
/*=wlb
/*.cfm=wlb
/*.cfc=wlb
/*.cfml=wlb

d. Create C:\Program Files\Tomcat6\conf\workers.properties and paste the following into it

# workers.properties.minimal -
# This file provides minimal jk configuration properties needed to connect to Tomcat.
# The workers that jk should create and work with
worker.list=wlb,jkstatus
# Defining a worker named ajp13w and of type ajp13
# Note that the name and the type do not have to match.
worker.ajp13w.type=ajp13
worker.ajp13w.host=localhost
worker.ajp13w.port=8009
# Defining a load balancer
worker.wlb.type=lb
worker.wlb.balance_workers=ajp13w
# Define status worker
worker.jkstatus.type=status
####################################

Okay boys and girls, now we've got everything in place from The Connector back to Tomcat; it's time for us to connect The Connector to IIS! (note: I am assuming at this point that you are able to navigate to localhost and your other domains already, viewing at least a default html page)

Tell IIS It's Okay To Run the DLL
1. In IIS Manager, click the main host, then double click the "Isapi and CGI Registrations" Icon
2. In the right hand panel, click the 'Add' link, then fill in the path to your dll as well as a name (any name will do). Be sure to check the little box!
Link Up Your Filter to Your Site
3. Click on your server's default site ("Default Web Site") and double click the ISAPI Filters icon.
4. In the right hand panel, click the Add link and fill in the name of your filter (the name you gave it in the previous step) and the path to the dll.
Create a Very Special Virtual Directory in Your Site
5. Right click on your Default Web Site and select 'Add Virtual Directory'. Name it 'Jakarta', and point it to C:\inetpub\scripts

6. Click on the Jakarta virtual directory, then double click on the 'Handler Mappings' icon

7. In the right hand panel, click on the link named "Edit Feature Permissions", then check the "Execute" box and close.

8. Restart IIS, restart your default web site (just for good measure), restart Tomcat, drop in a test index.cfm file into your default web root, and see if you can navigate to localhost/index.cfm! It should work at this point.

Repeat Steps 3 through 7 for Remaining Domains
Now, go back through steps 3 through 7 to get your remaining domains ready to use Railo. Skip step 8 for the time being (at least the part about browsing to an index.cfm), because we have to dive back into Tomcat before those domains will know what to do with a .cfm file.

Your Other Domains and Tomcat
Tomcat comes pre-configured with localhost, so for that domain we don't have to do anything. But for any other domains you may be wanting to run on this server, we're going to have to tell Tomcat that they exist and a few things about them. Your domains will now be referred to as 'Hosts', and we'll be working inside C:\Program Files\Tomcat6\conf\server.xml to set them up.

Let's say that IIS is also hosting a domain called MyDomain.Net. For development purposes, you will also be referring to this domain locally as "MyDomain-Test". Your domain's web root is located at C:\inetpub\wwwroot\mydomain.net, and you already have an entry in your hosts file (MyDomain.net MyDomain-Test) to allow you to successfully navigate to MyDomain.net via http://MyDomain-Test.

What we need to do is create another <Host> entry in our server.xml file that defines this host AND its known alias. Here is the snippet you should paste in to your server.xml file (values replaced appropriately with your own, of course), just below the localhost entry:

<Host name="MyDomain.net" appBase="webapps"
    unpackWARs="true" autoDeploy="true"
    xmlValidation="false" xmlNamespaceAware="false">
    <Alias>MyDomain-Test</Alias>
    <Context path="" docBase="C:\inetpub\wwwroot\mydomain.net"/>
</Host>

(note: make sure you understand the Context tag and the Alias tag in the above snippet. You can have multiple Alias tags, but you must make sure that the alias actually resolves before its of any use here. Either DNS entries are in place, or the Hosts file is being used for local resolution. Context is important because that is what tells Tomcat where to look for the files being requested.)

Save server.xml, restart IIS, restart your web sites, then restart Tomcat. You should now be able to successfully navigate to http://MyDomain.net/index.cfm as well as http://MyDomain-Test/index.cfm!

Troubleshooting Hints
Hopefully everything went well, but if not, don't panic. First, check your Tomcat log file to see if it had any issues starting up due to configuration errors (type-os, paths, etc.). You can find the log file at C:\Program Files\Tomcat6\logs\catalina.2009-09-04.log (or whatever today's date is for you). Remember that in this log file, latest entries are appended to the bottom. You can also eliminate some things by verifying that you can browse to your domain in IIS (calling a standard html page, not the cfm page), and in Tomcat by browsing to your domain with a specified port. In our sample above, we could perform this troubleshooting by browsing to http://MyDomain.net/default.htm , and http://MyDomain.net:8081/default.htm . If both of those resolve correctly, then try browsing directly to your .cfm page with http://MyDomain.net:8081/index.cfm. If that parses correctly, we know that Railo is doing its job and that the issue is probably somewhere in the redirection portion of things, meaning we should review our web sites' IIS settings again and the values in the properties files related to our DLL.

TIPS AND POINTERS
Default Files
In my scenario, I have to run both PHP files AND CFM files from the same domain. IIS already knows what to do with PhP files via an ISaPI mapping associating the PHP executable with files of that extension. And, the way the Tomcat connector dll works, it looks at every request to that domain to determine if it should redirect or not. SO then...what if I want the url http://MyDomain.net to default to index.php instead of index.cfm? Two pieces to that puzzle.

1: Within IIS, you can specify the order that default documents should be looked for regarding any given site. Just click the site, then the "Default Document" icon If you want

index.php to be the default document, simply make sure index.php appears before index.cfm, or leave index.cfm out of the list altogether.

That's half of the issue. The other half is the dll that sniffs every single request to determine if it should redirect or not. The snippet I gave you earlier for C:\inetpub\scripts\isapi_redirect-1.2.28.properties included the line " /*=wlb ". This line essentially tells the redirector, "redirect everything to Tomcat". Remove or comment out that line, and then ONLY the requests for files with the specific CFML extensions will be redirected for processing.

flex2gateway
I had a conversation with Paul Kukiel regarding an issue he was having getting flex2gateway to resolve without having to specify the port. Now, Paul was using IIS6 in that instance, so this solution doesn't apply, but I found that I myself wasn't able to get flex2gateway to resolve in my scenario either. The solution was simply adding this line to C:\inetpub\scripts\isapi_redirect-1.2.28.properties: " /flex2gateway/*=wlb "

Basically, any process you want to run that needs Railo to do the work, add an appropriate filter to the DLL's properties file so that it will know to redirect the processing to Tomcat.

That's all folks, and quite a lot it is. Any corrections or comments or suggestions or other tips and tricks are welcome!

<<	May, 2009					>>
S	M	T	W	T	F	S
					1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31

Name:		Required
Email:		Required your email address will not be publicly displayed.

My Score: 9,001

Read (and recommend)

Reading

Time to take the Turing Test!!!