The following versions of Tomcat are supported:
With Orbeon Forms 2018.1 and 2018.2
Tomcat 8.0 and 8.5
Tomcat 9
With Orbeon Forms 2017.2:
Tomcat 7
Tomcat 8.0 and 8.5
Tomcat 9
With Orbeon Forms 2017.1:
Tomcat 6 (not recommended, see note below)
Tomcat 7
Tomcat 8.0 and 8.5
About Tomcat 6:
Tomcat 6 isn't supported by Orbeon Forms starting with version 2017.2 as the Apache Tomcat team has announced that support for Apache Tomcat 6.0.x ended on December 31, 2016.
TIFF support is not available when using Tomcat 6 (see #2717).
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.
Create a new TOMCAT_HOME/webapps/orbeon
directory.
Unzip orbeon.war
in the orbeon
directory you just created. So now you should have a directory TOMCAT_HOME/webapps/orbeon/WEB-INF
.
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).
Edit TOMCAT_HOME/conf/server.xml
, and inside the <Host>
create a <Context>
as follows, changing the value of the docBase
attribute as appropriate on your system. Make sure the <Context>
element is within the <Host>
element. Tomcat will not report an error if your context is misplaced in the file, and that will cause it to be ignored and, in particular, datasources might not be taken into account.
<Contextpath="/orbeon"docBase="TOMCAT_HOME/webapps/orbeon"reloadable="false"override="true"allowLinking="true"/>
If you have a JDBC datasource, add it inside the <Context>
, as in the following example:
<Contextpath="/orbeon"docBase="/path/to/orbeon-war"reloadable="false"override="true"allowLinking="true"><Resourcename="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&characterEncoding=UTF8"/></Context>
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.
To setup Form Runner authentication:
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.
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"><RealmclassName="org.apache.catalina.realm.UserDatabaseRealm"resourceName="UserDatabase"/></Realm>
Edit TOMCAT_HOME/conf/tomcat-users.xml
and replace the content of the file with:
<tomcat-users><userusername="orbeon-user"password="Secret, change me!"roles="orbeon-user"/><userusername="orbeon-admin"password="Secret, change me!"roles="orbeon-user,orbeon-admin"/></tomcat-users>
Enumerate the roles in the following property:
<propertyas="xs:string"name="oxf.fr.authentication.container.roles"value="orbeon-user orbeon-admin"/>
If you are using BASIC authentication on Tomcat 6.0.21 or newer you might have to add the following <Valve>
element inside the <Context>
corresponding to the Orbeon Forms web app in Tomcat's configuration:
<ValveclassName="org.apache.catalina.authenticator.BasicAuthenticator"changeSessionIdOnAuthentication="false"/>