Tomcat
The following versions of Tomcat are supported:
Orbeon Forms Version | Tomcat Versions | Comment |
---|---|---|
2019.2, 2020.1, 2021.1, 2022.1 | 8.5, 9 | Tomcat 10 is not backwards compatible with earlier versions, and at this point is not supported by Orbeon Forms |
2019.1 | 8.5, 9 | |
2018.2 | 8.0, 8.5, 9 | Tomcat 8.0 not recommended, see below |
2018.1 | 8.0, 8.5, 9 | Tomcat 8.0 not recommended, see below |
2017.2 | 7, 8.0, 8.5, 9 | Tomcat 8.0 not recommended, see below |
2017.1 | 6, 7, 8.0, 8.5 | Tomcat 6 and 8.0 not recommended, see below |
Notes about older versions of Tomcat:
- The Apache Tomcat team has announced that support for Apache Tomcat 6.0.x ended on December 31, 2016.
- Tomcat 6 isn't supported by Orbeon Forms starting with version 2017.2.
- Tomcat 8.0 isn't supported by Orbeon Forms starting with version 2019.1, but Tomcat 8.5 is supported.
We assume below that
TOMCAT_HOME
represents the location of your Tomcat installation.- 1.Create a new
TOMCAT_HOME/webapps/orbeon
directory. - 2.Unzip
orbeon.war
in theorbeon
directory you just created. So now you should have a directoryTOMCAT_HOME/webapps/orbeon/WEB-INF
. - 3.You can now start Tomcat, and access
http://localhost:8080/orbeon/
to test your installation (replacinglocalhost
and8080
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.<Context
path="/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:<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&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:
- 1.Open
TOMCAT_HOME/webapps/orbeon/WEB-INF/web.xml
and uncomment thesecurity-constraint
,login-config
andsecurity-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"><RealmclassName="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><userusername="orbeon-user"password="Secret, change me!"roles="orbeon-user"/><userusername="orbeon-admin"password="Secret, change me!"roles="orbeon-user,orbeon-admin"/></tomcat-users> - 4.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:<Valve
className="org.apache.catalina.authenticator.BasicAuthenticator"
changeSessionIdOnAuthentication="false"/>
Last modified 1mo ago