A Guide to running Railo on Windows with Helicon zoo

Railo Add comments

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.

    image
    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>



 
Now simply edit the arguments element or you could optionally use the specified start.ini if you know how.

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>



 



Now you can use new environment variables within your web.config file as follows.


<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" /> 

 

 

 

15 responses to “A Guide to running Railo on Windows with Helicon zoo”

  1. Gerald Guido Says:
    Good stuff. I am a big fan of Helicon zoo. I am more of a Linux/Apache guy but Helicon zoo is very impressive. I know what a chore it can be to get things like Redmine up and running on IIS. I will need to try the Railo installer. Thanx for sharing.
  2. Yaroslav Govorunov Says:
    Thank you very much for the wonderful article!
    I’d like to add few clarifications. It is recommended to install “CFML Hosting Package” instead of installing Railo, Helicon Zoo Module and JDK separately. The CFML Package already includes all dependencies and will install just fine on a clean system without additional requirements. Installing components separately you may forget to install some essential components or install it in improper sequence. For example mentioned problem with JDK installation may occur when JDK is installed before Helicon Zoo Module, which is currently required. Installing CFML Hosting Package ensure all components are installed in right sequence. Also installing Railo 3/4 project” will install all requirements for selected IIS target version (IIS or IIS Express).
    We will investigate mentioned problem with java agent and provide a solution soon. Currently we are working hard on a Zoo version 3, which will be a significant improvement over current version, that is why current fixes are not coming fast.
    Thank you again, Russ!
  3. Russ Michaels Says:
    Yaroslav, I did try the "cml hosting package" once, and it wanted to install a whole bunch of other stuff which I did not want, including various SQL Server components.
  4. Yaroslav Govorunov Says:
    Are you sure you have tried "CFML Hosting Package"? Because various irrelevant SQL components may indicate installation of WebMatrix, that is a dependency for IIS Express installation and that is the dependency when you install the application (like Railo 4 project) while selecting IIS Express as a target installation server in options. Select IIS instead of IIS express and it will not try to install all these components.
  5. shifuimam Says:
    I just installed Helicon Zoo and Railo 4 on my Server 2012 box. Every single time I even refresh a Railo page, it's launching a new instance of java.exe. After about ten instances of Java, everything goes kaput and I have to force-kill all instances before it starts working again.

    Is there a way to make the Helicon Zoo installation of Railo run inside a SINGLE Java VM?
  6. Russ Michaels Says:
    That is how it is supposed to work as it is isolating each site in its own java process Thus providing extra security and perfornance benefits.
    If you just want a bog standard single java instance setup then use the regular tomcat version on the railo website.
  7. Marco Betschart Says:
    Wonderfull article!!!!

    Not more to say :)
  8. mario Says:
    Great article and very helpful. I have a couple of issues. When i make the change highlighted in "how to set the java agent" and restart the engine, the message still appears that no Java Agent is enabled. The other issue i have at the moment is that my session variables keep getting reset or the session is not being maintained. Even with the session management settings configured. Its truly puzzling. Have you come across this before and what are the optimum settings in the railo administrator/web for performance and session management.
  9. Russ Michaels Says:
    You should check that the section you have added java arg to matches the definition you are using in your web.config.
    i.e. you added it to railo.4 and not railo4, which is just there for backwards compatibility with previous versions.

    Losing sessions is most likely down to the reasons mentioned in the linked article "caveats of running Railo on Helicon Zoo" - http://www.michaels.me.uk/post.cfm/caveats-with-railo-running-on-helicon-zoo
  10. mario Says:
    Thanks for the reply.
    i noticed the application pool is currently v2 and not v4. in addition its using classic mode. would this make a difference? we fixed one issue the web.config settings for the handler and application name were different.
  11. Russ Michaels Says:
    I doubt using v2 or v4 would make any difference, but using classic made may well be causing issues.
  12. Sean Says:
    Thank you for your help with a great connector! YOu have saved me hours of trouble!! Thank kindly,

    Its almost working. I must be doing one thing wrong, its not working. DO we have to use a particular port? What is the application pool, Default? Or the name of the WEb we are creating.
  13. Russ Michaels Says:
    Hi Sean,

    i'm afraid I can no longer recommend Helicon Zoo for Railo. The version mentioned in this article has since been depreciated and replaced with a new version which runs as a service to address the issues I mentioned in my "caveats" article. Unfortunately I have never been able to get the new version to work on any machine, and couldn't get any support from Helicon, so had to stop using it. I am not sure it really provides any advantage over the regular Railo installer now.
  14. Yaroslav Govorunov Says:
    Hello Russ.

    We have developed this new version that runs as a service following your request. Actually both versions can be installed side by side. I am sorry to hear that you had problems with using it. Unfortunately I cannot find any support requests from you on our support portal that rely to these issues. If you still willing to use the software, please contact our support service with details and we will provide you all the help we can.
  15. Russ Michaels Says:
    Yaroslav, the last ticket id is [zoo-20322].
    I did wait several months for a reply, but in the end had to give up as I needed a working Railo installation. As I said, I trie dit on windows 7, windows 8, and windows server, and it never worked.

Leave a Reply

Leave this field empty

Powered by Mango Blog. Design and Icons by N.Design Studio