Adding new sites to Railo demystified

One of the questions that comes up quite often on the Railo Google Group is how to add sites to Railo after the initial installation. I can understand the frustration many new users feel because I was in their shoes many moons ago. I will agree that ACF does a fair bit of magic with the JRun connector, but with a little know how you will have your sites up and running in no time at all.

As a rule of thumb, every site you configure with Railo requires you to edit two configuration files no matter what OS you are running on. First you will need to add an entry in Railo’s server.xml to make it aware of your new site and finally add the site to Apache. I am going to assume you are using Jordan’s excellent Railo installer and you have completed the install process and Railo is connected to Apache. If you are on Windows you can refer to this post which covers installing the Apache connector.

First let us add our new context to Railo. Assuming you used the installer with your default options you can find your server.xml file in /opt/railo/tomcat/conf. The default context is already configured for you and we won’t mess with that. Commented out you will see a template for adding additional sites.

  Add additional VIRTUALHOSTS by copying the following example config:
  [ENTER DOMAIN NAME] with a domain, IE:
  [ENTER SYSTEM PATH] with your web site's base directory. IE: /home/user/public_html/ or C:\websites\\ etc...
  Don't forget to remove comments! ;)
  <Host name="[ENTER DOMAIN NAME]" appBase="webapps"
       unpackWARs="true" autoDeploy="true"
       xmlValidation="false" xmlNamespaceAware="false">
       <Context path="" docBase="[ENTER SYSTEM PATH]" />

So using this as a template, we are going to add in a new Railo host

<Host name="" appBase="webapps"
     unpackWARs="true" autoDeploy="true"
     xmlValidation="false" xmlNamespaceAware="false">
     <Context path="" docBase="/var/www/" />

As you can see, we are adding a new host for where the template had [ENTER DOMAIN HERE]. Next we enter the docBase where [ENTER SYSTEM PATH] is the location of the web root in the file system. In this case I have my webroot in /var/www/ This is important because the WEB-INF for this context will be created in this directory. Also note that this directory must be writable to the user assigned to the Railo service otherwise Railo will not be able to write the WEB-INF folder and all sorts of tomfoolery will happen. After saving the file you will need to restart the Railo service for your changes to take effect. On Linux this is easy as:

sudo /opt/railo/railo_ctl restart

If your changes were successful you should now be the proud new owner of a WEB-INF folder in /var/www/ If everything went smoothly here you are ready to move to the next step, which is adding your host configuration to Apache. If the folder is not there, more than likely there is a permission issue with your Railo user account. To see which user your Railo service is running under go to open up /opt/railo/railo_ctl with your favorite editor or just cat the file and look for the $TOMCAT_OWNER variable and check the permission on your webroot and make sure that user has write access to the folder.

So assuming everything went smoothly getting your site setup in Railo the next step is getting your virtual host configured in Apache. The location of your configuration files depends on your distribution, but assuming you are running Apache 2.2 on a Debian-based distribution you will need to add a new virtual host into /etc/apache2/sites-available.

Here are the contents of the /etc/apache2/sites-available/ file:

<VirtualHost *:80>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/
        DirectoryIndex index.cfm
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        <Directory /var/www/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride None
                Order allow,deny
                allow from all

        RewriteEngine on
        RewriteRule ^/railo-context/admin/(.*) - [F]
        RewriteRule ^/securelocation/(.*) /railo-context/admin/$1 [PT]

        ErrorLog ${APACHE_LOG_DIR}/

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/ combined


This is a basic virtual host configuration file. I set the DocumentRoot for this host. It should exactly match the docBase set when adding the Railo host. We also set the Apache directory permissions for the web root directory. For extra credit we are also adding some default rewrite rules to hide the Railo administrator and move it to a more secure location. The rewrite rules require that mod_rewrite is enabled on your server so check your main httpd.conf file to ensure it is enabled otherwise you will receive an error when trying to start Apache and it will fail.

To enable the new site we will need to create a symlink in /etc/apache2/sites-enabled. Forgive me if the parameters are wrong below, I am just doing this from memory.

sudo ln -s /etc/apache2/sites-available/ /etc/apache2/sites-enabled/

Now it is time to restart Apache to start serving from your new virtual host. This is generally as simple as sudo service apache2 restart, but this may vary from distribution to distribution.

Once Apache is restarted, you should now be able to point your browser to and view your web site. You can reach your admin pages by going to


About Robert Zehnder

Web application developer specializing in ColdFusion/Railo and Open Source development.

Posted on November 16, 2011, in Railo and tagged . Bookmark the permalink. 5 Comments.

  1. Thank you, thank you, thank you. And again, a thousand times, THANK YOU! Greatest blog post in the history of the Internet so far today! Signed, one of those new Railo users.

  2. Hi there

    I have just installed Railo and it installed TomCat as well on the server.

    I already had IIS7 installed and running on the server.

    I’m now wondering where do I place the folder for the new website.

    Does it go in c:/inetpub/wwwroot/newfolder

    or do I place the folder somewhere in C:/railo/tomcat

    I’m not 100% sure where I should place the new folder with the new website.

    Thanks in advance

  3. I was stumbling all over myself. Thank you for emphasizing the need to change ownership of the new site–that was my problem.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: