Tomcat
Last updated
Last updated
Installing Orbeon Forms on Tomcat is only one of the possibilities. You can also install Orbeon Forms on other Servlet containers. You can also use Docker containers. See also:
Docker
Servlet containers
The following versions of Tomcat are supported:
2024.1
9, 10
2023.1
8.5, 9, 10
2019.2, 2020.1, 2021.1, 2022.1
8.5, 9
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:
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.
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.
Unless you have another front-end performing stream compression, it is important to tell Tomcat to enable gzip compression on its connectors. This makes the amount of data transferred for JavaScript and CSS assets, in particular, significantly smaller. You can enable this on the Tomcat <Connector>
elements in server.xml
with the compression="on"
attribute. For example:
You can check that compression is working in your browser's Dev Tools' Network tab, where the two sizes indicate the compressed size and the uncompressed size:
Response headers will also include a Content-Encoding: gzip
response header on pages and most text assets.
If you have a JDBC datasource, add it inside the <Context>
, as in the following example:
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:
Edit TOMCAT_HOME/conf/tomcat-users.xml
and replace the content of the file with:
Enumerate the roles in the following property:
For BASIC or DIGEST authentication, add the following <Valve>
element within the <Context>
element corresponding to the Orbeon Forms web application in Tomcat's configuration. Remove this <Valve>
element if switching to FORM authentication, as leaving it will enforce BASIC or DIGEST authentication regardless of the configuration in web.xml
.
The Apache Tomcat team has that support for Apache Tomcat 6.0.x ended on December 31, 2016.
The Apache Tomcat team has that support for Apache Tomcat 8.0.x ended on June 30, 2019.
is not available when using Tomcat 6 (see ).
If using Orbeon Forms PE, make sure the license.xml
file is .
We recommend you add the URIEncoding="UTF-8"
attribute on the element, in your server.xml
, as . 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.