Railo Developer

Update Apr. 19, 2011: Version 0.4.01 + 0.4.02 (bug fix). Made sure that the code is run at the moment the directoryListener is initiated. Logging is now done with cflog (file named "VHostCopier"), to enable easier debugging.
Update Dec. 19, 2010: Version 0.3.02. A 'localhost' host will now always be created, even if not found in the webserver config; error message text changed at the check if multiple wildcard hosts were found.
Update Oct. 30, 2010: Version 0.3.01. Bug fix in the display of changed sites: if a site was previously found, and now deleted, an error occured.
Update Oct. 17, 2010: Version 0.3.00. It now also copies aliases/virtual directories from Apache/IIS to tomcat :-))
Update Oct. 10, 2010: Version 0.2.8. Changed component creation from "new ...()" to createobject(), so the code can be used on Railo 3.1. Also fixed var-scoping issues in some components.

If you use Railo as your cfml server, and use Apache or IIS as your main webserver, then you must have noticed that you need to add virtualHosts in 2 places. Once in the webserver, and once in Resin/Tomcat/Jetty, or whatever the JEE engine is you are running Railo on. This approach gets a lot of complaints, because people switching from Adobe Coldfusion (ACF) never had to do this. "It just worked".
The reason it works like that in ACF, is that Coldfusion has an ingenious connector between your webserver and JRUN (the JEE engine where ACF runs on). As far as I know, this connector tells JRUN what the webroot is for every request, and what virtual mappings are there.

Now I did a lot of investigation in finding out if this ACF approach could also be used for Railo, but to no avail. There is an AJP13 Extension Proposal for the connector between Tomcat and Apache, where this approach is mentioned, but it is still only a proposal.

So I thought of another way to make sure Railo knows what virtualhosts are available: by copying all virtualhost directives from Apache/IIS to the Railo server. As you can see in the title of this post, it copies them to Tomcat. That's because Tomcat is going to be the default JEE engine for Railo.

The code

• Download the current version 0.4.02
  
• You can view all the source code in my subversion browser

Test the webserver configuration parsing

Note: you do not need to have tomcat installed to use this test functionality. It will only try to parse your IIS/Apache configuration files.

I created code which parses the Apache/IIS config files, gets the virtualhosts out of it, creates the necessary config xml for Tomcat, and adds newly found virtualHosts directly to Tomcat by using Tomcat's host-manager.

Now I have only been able to test the parser code on 3 machines, while there are probably 100's of webserver configurations. So my question to you: please download and extract the code, and run test.cfm to see if your config files are correctly parsed.
Afterwards, please let me know if everything went fine. If an error is caught, then it can be automatically sent to me, so I can start debugging right away. But this is a setting that you control from the test.cfm file. If you don't want to directly send any errors, that's okay. Then just let me know by adding a comment here, or mail me at the supplied email address in test.cfm.

Install as a Railo extension

The copier is available as a Railo extension! It will install the full version, not the test version! So it will actually overwrite your tomcat configuration. If you already configured virtual hosts in tomcat, they will be overwritten (although a backup of the server.xml file will be created). So: use with care!

To install:

1. Go to your Railo server administrator at http://localhost/railo-context/admin/server.cfm
2. Go to the link Extensions > Providers, and add the URL http://www.railodeveloper.com/ExtensionProvider.cfc
3. Now go to Extensions > Applications, and choose to install the "Webserver2Tomcat vhost copier".
4. Follow the installation steps, and you're done!
5. For debugging / checking what's going on with the extension, you can check the following files:
   1. Tomcat's config xml, where the <VHost> tags are added: {tomcat-install-dir}conf/server.xml
   2. Tomcat's ROOT.xml files per VHost, where the <Context> tags are added: {tomcat-install-dir}conf/Catalina/{hostname}/ROOT.xml
   3. VHost copier log, where messages, warnings, and errors are logged: {railo-root-path}/railo-server/context/gateway/webserver2tomcatVHostCopier/parserLog.log.
   4. Tomcat's host-manager, by default at http://localhost:8080/host-manager/html
   5. Railo's log files, especially DirectoryWatcher.log, exception.log, and gateway.log: {railo-root-path}/railo-server/context/logs/
   6. An event gateway (Directory listener) will be installed by the extension, you can check it out in your Railo server administrator at Services > Event gateways.

What gets installed

• A directory listener, which looks at the webserver configuration file(s) every 4 seconds, and triggers the VHost-copier when a change occurs.
• The VHost copier source code, which is used by the directory listener.

What the code does

Before the code can run, a config file must be created. This is done by the Extension installer, or by maually editing it from the test.cfm file.
The config file needs to know:

• what type of webserver you use
• where Apache's httpd.conf is located (if using Apache)
• where tomcat is installed, and on which port it runs
• login info for the tomcat host-manager

Then, the following steps are done:

1. The parser reads the config file
2. Parses the webserver configuration to retrieve all virtualhosts
3. Checks if there are any changes in the virtualhost (by looking at a backup file of the previously retrieved virtualhosts).
   Note: this backup file is not created when using the test.cfm file.
4. Creates the necessary <VHost> tags for all the virtual hosts, and writes them to Tomcat's server.xml file (overwriting any existing <VHost> tags)
5. Creates/deletes an xml file for every changed host, where the <Context docBase="{web-root-directory}" /> is written. These files are created in {tomcat-install-dir}conf/Catalina/{hostname}/ROOT.xml.
6. Every newly found and deleted virtualHost is directly added to Tomcat by using the Tomcat host-manager. Otherwise, tomcat would only pickup the new VHosts after a restart.
7. A backup file is created which contains info about the current virtualHost data.

Requirements (for the full version)

• The tomcat hostmanager must be enabled and running. Check this by going to http://localhost:8080/host-manager/html (or your own custom tomcat port)
• You must have a valid user for the host-manager. You can add a user by editing the file {tomcat installation directory}/conf/tomcat-users.xml to contain the following:
  <tomcat-users><role rolename="manager"/><role rolename="admin"/><user name="SOME NAME" password="SOME PASSWORD" roles="admin,manager"/></tomcat-users>
• createObject() function and <cfinvoke> tag must be allowed (not sandboxed)
• Railo must have read access to the Apache or IIS config files
• Railo must have write access to Tomcat's server.xml file, and the directory {tomcat-install-dir}/conf/Catalina/

Limitations

I have not yet taken a look at the IIS-to-tomcat ISAPI filters,  so I am not sure if you need to do some extra configuration within IIS to map cfm and cfc files to be handled by Tomcat.

In Apache and IIS, you can have the webserver listening to different ports and ip addresses, for the same hostname. If you have multiple virtualhosts which have the same hostname, but use a different webroot, then this VHostcopier won't work. This is because Tomcat only checks the hostname, not the listening port or ip address.
An example Apache configuration where this happens is:

<VirtualHost *:80>
    DocumentRoot /websites/mysite.com/
    ServerName www.mysite.com
</VirtualHost>
# SSL website, pointing to another webroot, but with the same hostname:
<VirtualHost *:443>
    DocumentRoot /websites/securestuff.mysite.com/
    ServerName www.mysite.com
</VirtualHost>

So you read the whole article? Great!

Would you then please also take the time to test this code? And let me know what happened? Great!