Tomcat

Supported Tomcat versions

As of Orbeon Forms 2016.1 and 2016.2, the following versions of Tomcat are supported:

  • Tomcat 6 (not recommended, see below)
  • Tomcat 7
  • Tomcat 8

NOTES:

  • The Apache Tomcat team has announced that support for Apache Tomcat 6.0.x will end on December 31, 2016. We don't recommend using Tomcat 6 after that date.
  • TIFF support is not available when using Tomcat 6 (see #2717).

Setup

We assume below that TOMCAT_HOME represents the location of your Tomcat installation.

If using Orbeon Forms PE, make sure the license.xml file is in place.

Quick setup

  1. Create a new TOMCAT_HOME/webapps/orbeon directory.
  2. Unzip orbeon.war in the orbeon directory you just created.
  3. You can now start Tomcat, and access http://localhost:8080/orbeon/ to test your installation (replacing localhost and 8080 with the host name and port number of your Tomcat installation if different from the default).

Custom context

You can setup the Tomcat context directly within the Orbeon Forms WAR under TOMCAT_HOME/webapps/orbeon/META-INF/context.xml. For example, to add a datasource:

<Context>
    <Resource
        name="jdbc/mysql"
        driverClassName="com.mysql.jdbc.Driver"

        auth="Container" 
        type="javax.sql.DataSource"

        initialSize="3" 
        maxActive="10" 
        maxIdle="10" 
        maxWait="30000"

        poolPreparedStatements="true"

        testOnBorrow="true"
        validationQuery="select 1"

        username="orbeon"
        password="password"
        url="jdbc:mysql://localhost:3306/orbeon?useUnicode=true&amp;characterEncoding=UTF8"/>
</Context>

Custom context within server.xml

This is an alternate way of deploying with Tomcat, which gives you more control as to where the Orbeon Forms files are located.

First, unzip the Orbeon Forms WAR file into a directory of your choice, for example:

/path/to/orbeon-war

This means that under the orbeon-war directory, you should have a WEB-INF directory.

Then create a context in Tomcat's server.xml, for example:

<Context
    path="/orbeon"
    docBase="/path/to/orbeon-war"
    reloadable="false"
    override="true"
    allowLinking="true"/>

Note that if you have a JDBC datasource, you can also place it inside:

<Context
    path="/orbeon"
    docBase="/path/to/orbeon-war"
    reloadable="false"
    override="true"
    allowLinking="true">
    <Resource 
        name="jdbc/mysql"
        driverClassName="com.mysql.jdbc.Driver"

        auth="Container" 
        type="javax.sql.DataSource"

        initialSize="3" 
        maxActive="10" 
        maxIdle="10" 
        maxWait="30000"

        poolPreparedStatements="true"

        testOnBorrow="true"
        validationQuery="select 1"

        username="orbeon"
        password="password"
        url="jdbc:mysql://localhost:3306/orbeon?useUnicode=true&amp;characterEncoding=UTF8"/>
</Context>

Optional steps

URIEncoding

We recommend you add the URIEncoding="UTF-8" attribute on the <Connector> element, in your server.xml, as recommended in the Tomcat FAQ. This will ensure that all characters get properly decoded on the URL, which is especially important if you're using non-ASCII characters in the app or form name in Form Builder.

Form Runner authentication

To setup Form Runner authentication:

  1. Open TOMCAT_HOME/webapps/orbeon/WEB-INF/web.xml and uncomment the security-constraint, login-config and security-role declarations at the end of the file.
  2. Open TOMCAT_HOME/conf/server.xml and make sure there is a <Realm> enabled. For example, by default with Tomcat 7:

     <Realm className="org.apache.catalina.realm.LockOutRealm">
         <Realm
             className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase"/>
     </Realm>
    
  3. Edit TOMCAT_HOME/conf/tomcat-users.xml and replace the content of the file with:

     <tomcat-users>
         <user
             username="orbeon-user"
             password="Secret, change me!"
             roles="orbeon-user"/>
         <user
             username="orbeon-admin"
             password="Secret, change me!"
             roles="orbeon-user,orbeon-admin"/>
     </tomcat-users>
    
  4. Enumerate the roles in the following property:

     <property
       as="xs:string"
       name="oxf.fr.authentication.container.roles"
       value="orbeon-user orbeon-admin"/>
    

BASIC authentication

If you are using BASIC authentication on Tomcat 6.0.21 or newer, or on Tomcat 7, then you need to add the following valve inside the <Context> corresponding to the Orbeon Forms web app in Tomcat's configuration:

<Valve
    className="org.apache.catalina.authenticator.BasicAuthenticator"
    changeSessionIdOnAuthentication="false"/>

results matching ""

    No results matching ""