Installing Orbeon Forms, Tomcat and your application side by side on Ubuntu

One of the huge benefits of Debian based distributions (such as Ubuntu) is their packaging system that let you apply security updates on all the software that is installed on your system through a single command.

It is a strong motivation to prefer to install software through distribution packages rather than from their developer downloads and that applies to tomcat which is a common choice as a servlet container to power Orbeon Forms applications.

The Orbeon Forms’ installation guide describes two ways of installing on Tomcat. The first one is basically unzipping Orbeon Forms in the Tomcat’s webapp directory.

This is working fine, but rather than adding stuff to the /var/lib/tomcat7/webapps directory, I usually prefer to give Orbeon Forms its own location and use the second method « Apache Tomcat with a custom context« . If you are using the tomcat7 Ubuntu or Debian package, the context file (that can be called orbeon.xml) should go in the /etc/tomcat7/Catalina/localhost/ directory.

On my laptop, with Ubuntu 12.04 and Tomcat7, this configuration is working out of the box.

Now that we’ve installed Orbeon Forms physically « side by side » with Tomcat rather than within a Tomcat directory, what about installing your Orbeon Forms application side by side with Orbeon Forms rather than installing into the Orbeon Forms directories?

This is also possible using Orbeon Forms resource managers! This is a technique that is used in development mode and in web.xml you can find the following comment:

    <!-- Uncomment this for the filesystem resource manager (development mode) -->
    <!--
    <context-param>
        <param-name>oxf.resources.priority.1</param-name>
        <param-value>org.orbeon.oxf.resources.FilesystemResourceManagerFactory</param-value>
    </context-param>
    <context-param>
        <param-name>oxf.resources.priority.1.oxf.resources.filesystem.sandbox-directory</param-name>
        <param-value>/home/teamcity/TeamCity/buildAgent/work/278cc758fa087cef/src/resources</param-value>
    </context-param>-->
    <!-- End filesystem resource manager (development mode) -->

The context parameters that are commented basically say that resources will be searched in a specific directory (such as /home/teamcity/TeamCity/buildAgent/work/278cc758fa087cef/src/resources) before being searched in the Orbeon Forms WEB-INF/resource directory (which itself will be used before searching in the packages jar files, …).

To deploy your application side by side with the Orbeon Forms installation you can just uncomment these parameters and replace this directory by the location of your application. The documents that you’ll provide in this directory will then override the documents that might be in the Orbeon Forms installation.

There is probably a performance degradation associated with this mechanism but the benefits are really interesting: web.xml becomes the only file that you’ll update in the standard Orbeon Forms installation and changing Orbeon Forms versions becomes really easy.