Configuring Railo for the application server - Part 1

Lately we had several basic questions about how to configure Railo with Resin. This blog entry describes the different options one has when using Railo in a multi virtual host environment. The first part will explain the configuration of the Railo servlet.

In this example I will explain how to configure Railo with Resin. The two important files for this configuration are app-default.xml and resin.conf (note: starting with Resin 4.0 the file will be called resin.xml)

app-default.xml

So let's start with the app-default.xml. This file get's included by the file resin.conf. You can see the include command somewhere in this configuration file:
In this file the configuration of the Railo servlet is done. Take a look at the following block: Line 1 defines the Railo servlet and the path to the class where the servlet can be found. In line 3-4 and 8-9 the Railo configuration directories are defined. They are passed to the servlet as init parameters. The {railo-web-directory} is the directory that contains the railo-web.xml.cfm and all the necessary files for a web context. These files are for example, the Railo archive containing the Railo administrators (railo-context.ra), the scheduler and search settings, the client tasks and many more.
All these files are created when a web context is used for the first time or when an update to a later release has been applied. You can see these file creations in the log files of your app server on startup or when a web context is either initialized or used for the first time.
Important is that the railo-web-directory is unique for each web context. That's why there is the distinction in form of the variable {web-root-directory}. This is containing the path to each web context. So it will be different from web context to web context.

Tips and tricks concerning the railo-web-directory

• the additional sub-folders WEB-INF/railo aren't necessary. So you could have your Railo configuration directory named somehow different like {web-root-directory}/JohnDoe/. It's just that many application servers store their configuration files in the folder WEB-INF and that this folder is not accessible by someone other than the application server itself.
  
  
• In order to protect the railo-web-directory from the web root and possible outside attacks, you can use an additional level when you are defining a web context root and then use the following notation in the app-default.xml:
  2: <init-param>
  3:     <param-name>railo-web-directory</param-name>
  4:     <param-value>{web-root-directory}/../WEB-INF/railo/</param-value>
  5:     <description>Railo Web Directory directory</description>
  6: </init-param>
  
  This ensures that you have the WEB-INF directory stored one level above the web root.
  
  
• If you are in a clustered environment you must not use the same railo-web-directory for the same web-context on different servers in the cluster. Since the different servers might access some files (cfclasses for instance or config changes in the railo-web.xml.cfm) at the same time. Therefore it is important to store these configuration files in a different location. So you can use the following notation in the app-default.xml:
  2: <init-param>
  3:     <param-name>railo-web-directory</param-name>
  4:     <param-value>c:/railoconfig/{web-context-hash}/</param-value>
  5:     <description>Railo Web Directory directory</description>
  6: </init-param>
  
  The variable {web-context-hash} is different as well for each web context. So if you have defined n web contexts in your resin.conf that are using Railo you will have n folders in the directory c:\railoconfig. A different hash value for every single one. In order to keep the different folders apart, you have two options:
  1. You either go to the server admin and have a look at the start page. There every web root is mapped to its configuration directory. Works only starting at version 3.0.3 and 3.1.0.015.
  2. You have a look at the web application log file. There you'll find all web contexts that are used listed somehow like this:
     ===================================================================
     WEB CONTEXT
     -------------------------------------------------------------------
     - config:D:\Projects\getrailo.local\WEB-INF\railo
     - webroot:D:\projects\getrailo.local\
     ===================================================================
     
  This way you can store files in local directories and prevent access problems.
  
  

It is only important to set the railo-server-directory when you have no write access to the default location. The default location is inside the folder where the railo.jar is located.