Running XNAT on Tomcat 8.5 and Later

This section describes how to run XNAT, configure your environment, and monitor and troubleshoot the deployed XNAT application using Tomcat 8.5 or later.

As of version 1.8.2, XNAT runs on Tomcat 8.5 and later by default, but we strongly recommend using Tomcat 9.0.

• If you are running Tomcat 7.0, support for it  ended on 31 March, 2021  and it will be removed from many repositories before too long.
• XNAT is compatible with the official Apache releases of Tomcat 8.5, but there are known issues when running XNAT on  particular builds and deployments  of Tomcat 8.5.
• Newer operating systems and distributions such as Ubuntu 20.04 provide Tomcat 9.0 but require backporting or custom repositories to install Tomcat 8.5, which can mean important security patches or updates may be applied promptly.

As a result, we only officially support Tomcat 9.0. You should consider migrating to Tomcat 9.0 as soon as possible.

Modifying XNAT to run on Tomcat 8.5 or later

This section describes how to modify XNAT to run on Tomcat 8.5 or later.

Running XNAT 1.8.1 and earlier on Tomcat 8.5 and later

The default war for XNAT 1.8.1 and earlier is built to run under Tomcat 7.0 You should consider upgrading to XNAT 1.8.2 or later and running under Tomcat 8.5 or later, but if you can't:

1. Extract the file META-INF/context.xml (this requires having the Java JDK available on your path):

   Extracting META-INF/context.xml

   BASH

   $ jar xf xnat-web-1.8.1.war META-INF/context.xml

   
   This file should look something like this (edited for clarity):

   Default XNAT context.xml for Tomcat 7

   XML

   <?xml version="1.0" encoding="utf-8"?>
   <Context>
       <Loader className="org.apache.catalina.loader.VirtualWebappLoader" searchVirtualFirst="true" virtualClasspath="${xnat.home}/plugins/*.jar"/>
       <JarScanner scanAllDirectories="true" />
       <Parameter name="xnatHome" value="${xnat.home}"/>
       <Manager pathname="" />
   </Context>

2. Edit META-INF/context.xml and delete the line with the <Loader> element.

3. Add the following lines to the file right after the <Context> element:

   Context elements required for Tomcat 8.5 and 9.0

   XML

   <Resources>
       <PostResources className="org.apache.catalina.webresources.DirResourceSet" base="${xnat.home}/plugins" webAppMount="/WEB-INF/lib" />
   </Resources>
   <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />

4. Save the file and close your editor.

5. Update the war file with your modified META-INF/context.xml file:

   Updating META-INF/context.xml in XNAT

   BASH

   $ jar uf xnat-web-1.8.1.war META-INF/context.xml

6. Continue with your deployment/installation using the updated war file in place of the standard XNAT application.

The final version of your modified configuration file should look like this:

<?xml version="1.0" encoding="utf-8"?>
<Context>
    <Resources>
        <PostResources className="org.apache.catalina.webresources.DirResourceSet" base="${xnat.home}/plugins" webAppMount="/WEB-INF/lib" />
    </Resources>
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
    <JarScanner scanAllDirectories="true" />
    <Parameter name="xnatHome" value="${xnat.home}"/>
    <Manager pathname="" />
</Context>

The standard releases of XNAT 1.8.1 and earlier already have the lines required for compatibility with Tomcat 8.5 or later, but they're commented out. Delete the <Loader> element then delete the !-- string at the beginning of the <Resources> element and the -- string at the end of the <CookieProcessor> element.

Running XNAT 1.8.2 and later on Tomcat 8.5 and later

XNAT 1.8.2 and later requires no changes to run on Tomcat 8.5 or later.