Contents Create a Railo context Create a new context in Jetty Define a new host/web context in Resin Normal definition with fix paths Implicit definition with regular expressions Make use of the file hosts.xml in order to define new web contexts

Create a Railo context

Railo web contexts are very useful for separating different settings per virtual host like turning on debugging for one site and off for another or using different versions of a framework with the same mapping name. The creation of a context depends on the servlet engine you are running on. Below you will find the definitions for different servlet engines or application servers:

Create a new context in Jetty

For Jetty 6.0 and above this can be easily done by copying the railo.xml file in the directory /contexts and configure it accordingly. Just apply the following procedure:

1. Copy the file /contexts/railo.xml into for example /contexts/mycontext.xml
2. Change the content of the file as follows (Let's assume that you will create a new host (context) with the name "mycontext"):

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
<-- <==================================================================
...
===================================================================== -->
<Configure class="org.mortbay.jetty.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
<-- <The directory is located ander the root of the installation. You can enter an absolute path as well -->
<Set name="resourceBase"><SystemProperty name="jetty.home" default="."/>/mycontext/</Set>  <-- <Jetty reacts on the following files -->
  <Set name="welcomeFiles">
    <Array type="String">
      <Item>index.cfm</Item>
      <Item>index.cfml</Item>
      <Item>index.htm</Item>
      <Item>index.html</Item>
    </Array>
  </Set>
<-- <- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  <-- <Optional context configuration                                  -->
  <-- <- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  <Set name="extractWAR">false</Set>
  <Set name="copyWebDir">false</Set>  -->
  <Set name="defaultsDescriptor"><SystemProperty name="jetty.home" default="."/>/etc/webdefault.xml</Set>
  <-- <virtual hosts  -->
  <Set name="virtualHosts">
    <Array type="String">
      <Item>mycontext</Item>
    </Array>
  </Set>
</Configure>

1. Restart Jetty
2. Add a new entry into your local host-file with the IP address 127.0.0.1 and call it mycontext
3. call http://mycontext/railo-context/admin.cfm

You should now see the Railo administrator for the new context. You can check the existing contexts easily by doing one of the following:

• see if a WEB-INF directory has been created (this depends on your servlet configuration)
• check the main page of the Railo Server Administrator. There all contexts are listed
• check the startup log. There you will see a list of all the contexts that have been started. Please note that contexts might be created and used on the fly only, which means that they do not show up in the log file unless you use them for the first time.
• see if the changes you make in the administrator affect a different website

Define a new host/web context in Resin

Resin offers several different possibilities to define new web contexts. We will have a look at the three most popular ways of creating new web contexts.

Normal definition with fix paths

We have seen this definition of hosts or web contexts further above so we will just recap it here:

<host id="hostname" root-directory="rootdirectory">
	<web-app id="/" document-directory="filedirectory" />
</host>

For each web app defined here Resin will create a web context. In general you will only define one single web app which is the one with the ID „/“ and assign a directory to it. Here is an example for a new context definition:

<host id="club" root-directory="/var/www">
	<web-app id="/" document-directory="club" />
</host>

This means that the web root for this host is found in the directory /var/www/club. It is important that after changing the file resin.conf you need to restart the Resin service in order to reflect the changes. You can easily see whether the new web context has been created by checking the console output where Railo will create the necessary files for the context. We have seen this already a couple of times.

Advantages

• One advantage of this method is that you have all generated web contexts under „control“
• By explicitly defining them you can address any security problems

Disadvantages

• One big disadvantage is that the application server needs to be restarted on every change of the resin.conf file

For environments that seldom change this is a recommended method. Please just keep in mind the necessary automatic or manual restart of Railo/Resin.

Implicit definition with regular expressions

Next to the fix definition of host entries inside resin.conf you have the elegant possibility to define new web contexts automatically WITHOUT having to restart the application server. This is based on a feature that is provided by Resin. This feature allows you to use define host names and web contexts with the help of regular expressions. Here’s an example:

<host regexp="(.+)">
	<host-name>${host.regexp[1]}</host-name>
	<root-directory>D:/projects/${host.regexp[1]}</root-directory>
	<web-app id="/" document-directory="."/>
</host>

The above definition can be interpreted like this:

• Take any host name that comes from the web server
• Assign the host name to the web context
• Check the directory D:\projects for a directory that is named like the host name
• Set this directory as the document root
• Set the same directory as the document directory for the web-app with the ID „/“

In this way you can easily define new web contexts by creating a subfolder in the directory D:\Projects and of course a host name that points to the local IP address.

Advantages

• Very easy configuration
• Very flexible
• Several different configuration options
• Configuration by convention

Disadvantages

• Security wise a little tricky
• You can easily define host names and contexts by creating a directory and a host entry

By adding a web servers to the environment these disadvantages can be prevented.

Make use of the file hosts.xml in order to define new web contexts

Since Resin 3.1.x there is a new possibility of defining virtual hosts (web contexts) by creating an XML file without having to restart the application server. In order to do so you just need to create a folder called hosts in the Resin root directory and add all necessary hostnames as directories (like www.example.com) and place a file called host.xml in each directory defining different attributes of the web context. The big advantage here is that you can easily integrate this solution with cPanel or other management applications. A restart of the application server isn’t necessary with this definition of hosts as well. Let’s have a look at an example. You can easily create a directory named www.example.com and create a host.xml file in there that has the following content:

<host xmlns="http://caucho.com/ns/resin">
	<web-app id="/" root-directory="D:/whateverdirectory"/>
</host>

If you define a new web context, Railo creates all necessary files as soon as the application server invokes Railo for this web context for the first time. In this way you will have all that’s necessary in order to use the local Railo administrator for this web context. The created files do not have to lie within the web root directory. This can be configured differently.