Greetings Railo fans,

In this article I will be covering how to setup and configure Railo with the Helicon Zoo module for IIS and then configure various custom settings. I will continue to add to this article as I find out new tricks and learn more about Jetty, so be sure to check back occasionally if you are using Helicon Zoo.

Please also be sure to read my other article caveats with railo running on helicon zoo

Contents

1. Why Helicon zoo
2. Installing Railo
3. Enable Railo on your website
4. Search engine friendly url's
5. changing the JVM settings
6. How to set the Java Agent
7. Customising the JVM settings on a per site basis

Why Helicon Zoo

While Railo is a brilliant alternative to ColdFusion and has many benefits right out of the box, one of the problems it does suffer from is that like ColdFusion it runs as a service which means that every website is running inside the same instance of Java/tomcat and thus all websites can affect each other.
If you are only running a single website this is not a problem, but if you run multiple websites on the same server then this can present a couple of problems.

1. Security
   While Railo does offer built in sandboxing which restricts file access to the web root, this only applies to CFML code. If you drop in some Java then this completely overrides any Railo security and allows you to do pretty much anything you like. Your code will have the same level of access as the Tomcat service.
   Sure you can disable direct Java access, but doing this will break virtually every modern app or framework, all of which use Java in some fashion.
2. Stability and performance
   If you run multiple websites then you also run the risk that any one of those sites will kill Tomcat by coming all its resources and thus take down all your other sites in the process.
3. Custom configuration
   As all sites share the same JVM settings, there is no way to configure each site separate out of the box, you would need a custom multiple instance Tomcat setup/installation to do this.

Enter Helicon Zoo, which uses Jetty as the Java servlet container for Railo and runs it as a process inside IIS and thus works in the same way that PHP, ASP etc work with all the advantages.
What this basically means is that every single Railo site is by default running a dedicated instance of Java/Jetty, which runs as the application pool identity. As a result you do not have the same security issues as any Java code that is executed runs in the context of your application pool identity, so you can fully control what Railo can and cannot  do with standard windows permissions in the same way as you would with PHP.
Using Helicon Zoo also provides better performance and stability as well, because each site is a completely isolated Java process,  it cannot affect your other Railo sites. Because each site is running as a separate process, this also means that each site has its own memory heap all to itself, which can either be defined globally (e.g. 256mb for every site) or you can create completely a separate JVM config settings for each individual site if you prefer.

One other advantage you get with running Railo as a process is that it shuts down when not in use to conserve system resources, as defined by your application pool settings. 
what this means is that if you have a site that is not very busy then Java/Jetty/Railo will only be loaded when required, if there is no further activity on your site for say 1 hour (depending on what you have defined in your app pool) then the Java process for this site will be unloaded.
The only caveat to this is that initial load time will be considerably slower each time Java has to load again, plus of course you use more memory as each site will require at least 128MB to run Railo.

Installing Railo

• First you need to install Helicon Zoo, instructions on how to do this can be found HERE.
• Now that you have ZOO installed you can install Railo.
  From within WebsitePanel just search for "railo" in the search box, and you will get results like this.
  
  
  Now just choose your desired version of Railo, ADD it, and then install.
  If you choose "Railo 4 project", this will also create a sample website with all the handlers configured and ready to go, so you could then use this as a template for other sites.
  As part of the installation it will also install Jetty and JDK SE, if you have issues with either of these failing, then you can download and install them manually. I have consistently had issues with the JDK not installing via WEB PI.
  you can get the JDK SE from HERE.

Enable Railo on your website

You will need to have the following entries in your web.config file to enable Helicon zoo and add the new Zoo/Railo handlers.
This covers both 32 and 64 bit systems, you can safely remove the handlers you do not need. i.e if you're running 64 bit, remove the 32 bit handlers.

If you have previously had any other version of Railo installed, then you should also remove the old handlers, isapi filters and jakarta vDir within IIS and none of this is required.
If you have ColdFusion installed, then you should also remove the ColdFusion handlers as well.

 <?xml version="1.0" encoding="UTF-8"?>

<configuration>

   <system.webServer>

      <heliconZoo>

         <application name="railo4.project">

            <environmentVariables />

         </application>

      </heliconZoo>

      <handlers>

         <add name="railo.project#x86.cfm" scriptProcessor="railo.4" path="*.cfm" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x86.cfc" scriptProcessor="railo.4" path="*.cfc" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x86.cfml" scriptProcessor="railo.4" path="*.cfml" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x86.cfr" scriptProcessor="railo.4" path="*.cfr" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x86.cfswf" scriptProcessor="railo.4" path="*.cfswf" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x64.cfm" scriptProcessor="railo.4" path="*.cfm" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x64.cfc" scriptProcessor="railo.4" path="*.cfc" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x64.cfml" scriptProcessor="railo.4" path="*.cfml" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x64.cfr" scriptProcessor="railo.4" path="*.cfr" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />

         <add name="railo.project#x64.cfswf" scriptProcessor="railo.4" path="*.cfswf" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />

      </handlers>

   </system.webServer>

</configuration>

If you are using Railo 3 then simply replace

scriptProcessor="railo.4"

with

scriptProcessor="railo.3"

By the way, you can also install/run both Railo 3 and Railo 4 at the same time, and simply switch between them by changing the above handlers. Coldfusion will also run happily along side Railo 3 and 4 too, just remove the above handlers and enable ColdFusion Handlers instead.

Search engine friendly URL's

If you run Mango Blog, Mura CMS or any other apps which use SEF (Search Engine Friendly) URL's such as "page.cfm/some-page" then this will not work by default. You will need to add some additional servlet mappings to do this.

Open the following file for Railo 4
C:\Zoo\Workers\jetty\zoo-railo4\etc
or for Railo 3
C:\Zoo\Workers\jetty\zoo-railo3\etc

find the following section and add the required mappings, the last 3 are the ones required for Mango Blog for example.

  <?xml version="1.0" encoding="UTF-8"?>

<servlet-mapping>

   <servlet-name>CFMLServlet</servlet-name>

   <url-pattern>*.cfm</url-pattern>

   <url-pattern>*.cfml</url-pattern>

   <url-pattern>*.cfc</url-pattern>

   <url-pattern>*.cfm/*</url-pattern>

   <url-pattern>*.cfml/*</url-pattern>

   <url-pattern>*.cfc/*</url-pattern>

   <url-pattern>/index.cfc/*</url-pattern>

   <url-pattern>/index.cfm/*</url-pattern>

   <url-pattern>/index.cfml/*</url-pattern>

   <url-pattern>/page.cfm/*</url-pattern>

   <url-pattern>/post.cfm/*</url-pattern>

   <url-pattern>/archives.cfm/*</url-pattern>

</servlet-mapping>

Changing the JVM settings

Open your applicationhost.config file, you can find this is in c:\windows\system32\inetstv\config

Look for this section

<?xml version="1.0" encoding="UTF-8"?>

<add name="railo.4" displayName="Railo 4 on Jetty 8" fullPath="%JDK_HOME%\bin\java.exe" arguments="-Xmn64m -Xms128m -Xmx256m -Djetty.port=%PORT% -jar start.jar --config=%SystemDrive%\Zoo\Workers\jetty\zoo-railo4\start.config --ini=%SystemDrive%\Zoo\Workers\jetty\zoo-railo4\start.ini" deployArguments="-jar &quot;%APPL_PHYSICAL_PATH%\%DEPLOY_FILE%&quot;" transport="tcp" protocol="http" maxInstances="1">

   <environmentVariables>

      <add name="CURRENT_DIRECTORY" value="%SystemDrive%\jetty8" />

   </environmentVariables>

</add>



 

how to set the java agent

When you first install Railo and go into the server admin, you will get this message.

There is no Java Agent defined in this enviroment. The Java Agent is needed to improve memory (PermGen Space) consumption for templates. To enable the Java Agent follow this instructions:

1. Add the "-javaagent" JVM argument and set it to point to the railo-inst.jar
   (you can download it by clicking the Update JARs button on the Railo Server Administrator Update page)

To do this, edit the file mentioned above in "changing the JVM settings".
and add the following argument with the path to the railo-inst.jar file.

-javaagent: c:\railo4\railo-inst.jar

e.g.

arguments="-Xmn64m -Xms128m -Xmx256m -Djetty.port=%PORT% -jar start.jar -javaagent: c:\railo4\railo-inst.jar --config=%SystemDrive%\Zoo\Workers\jetty\zoo-railo4\start.config --ini=%SystemDrive%\Zoo\Workers\jetty\zoo-railo4\start.ini"

Customising the JVM settings on a per site basis

If you do not want all of your sites to have the same heap sizes and what not then you can customise this using the environment variables settings in your web.config.

First you need to edit the Railo engine settings in your applicationhost.config and replace the fixed variables with environment variables as follows, note the changes I have made in YELLOW.
Please also note that the environment variables are CASE SENSITIVE.

<?xml version="1.0" encoding="UTF-8"?>

<add name="railo.4" displayName="Railo 4 on Jetty 8" fullPath="%JDK_HOME%\bin\java.exe" arguments="-Xmn%Xmn% -Xms%Xms% -Xmx%Xmx% -javaagent:c:\railo4\railo-inst.jar -Djetty.port=%PORT% -jar start.jar --config=%SystemDrive%\Zoo\Workers\jetty\zoo-railo4\start.config --ini=%SystemDrive%\Zoo\Workers\jetty\zoo-railo4\start.ini" deployArguments="-jar &quot;%APPL_PHYSICAL_PATH%\%DEPLOY_FILE%&quot;" transport="tcp" protocol="http" maxInstances="1">

   <environmentVariables>

      <add name="CURRENT_DIRECTORY" value="%SystemDrive%\jetty8" />

      <add name="Xms" value="256m" />

      <add name="Xmn" value="64m" />

      <add name="Xmx" value="256m" />

   </environmentVariables>

</add>



 

<system.webServer>

         <heliconZoo>

         <application name="railo.project">

         <environmentVariables>

            <add name="Xms" value="512m" />

            <add name="Xmx" value="512m" />



         </environmentVariables>

It is important that the application name "railo.project" matches the name of the handler before the #

e.g.

 <add name="railo.project#x86.cfm" scriptProcessor="railo.4" path="*.cfm" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" /> 

Related Entries:

• Caveats with Railo running on Helicon zoo
• Railo: Dynamic host configuration
• Enabling Coldfusion/Railo errors on IIS 7
• Running Railo and ColdFusion 10 side by side with BonCode
• Railo filling up my catalina folder with random folder names

Views: 4785