Running XNAT on Tomcat 7

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

Modifying XNAT to run on Tomcat 7

This section describes how to modify the XNAT application to run on Tomcat 7.0.

As of version 1.8.2, XNAT runs on Tomcat 8.5 and later by default, with Tomcat 9.0 recommended. 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. You should consider migrating to Tomcat 9.0 as soon as possible. XNAT is compatible with the official releases of Tomcat 8.5, but there are known issues when running XNAT on particular builds and deployments of Tomcat 8.5. As a result, we only officially support Tomcat 9.0.

With the move to Java 8, XNAT 1.8 snapshot builds began seeing severe Catalina errors on versions of Tomcat prior to version 7.0.106. This has been generally reported on StackOverflow, and reported as an XNAT bug here. If you are using Apache Tomcat 7, we recommend using Tomcat 7.0.106 or later or upgrading to Tomcat 9.0 (if you are running XNAT 1.8.1 or earlier, we recommend upgrading to XNAT 1.8.2 or later to run with Tomcat 9.0, but if this isn't possible you can modify your older XNAT to run on Tomcat 8.5 or later).

Running XNAT 1.8.1 and earlier on Tomcat 7.0

XNAT 1.8.1 and earlier requires no changes to run on Tomcat 7.0.

Running XNAT 1.8.2 and later on Tomcat 7.0

The default war for XNAT 1.8.2 and later is built to run under Tomcat 8.5 and later. If you have Tomcat 7.0, you should consider upgrading to Tomcat 8.5 or later, but if you can't, follow these instructions to restore compatibility with Tomcat 7.0:

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.2.war META-INF/context.xml

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

Default XNAT context.xml for Tomcat 8.5 and later

XML

<?xml version="1.0" encoding="utf-8"?>
<Context>
    <Resources>
        <PreResources 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>

Edit META-INF/context.xml and delete the lines with the <Resources>, <PreResources> and <CookieProcessor> elements.

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

Context elements required for Tomcat 7.0

XML

<Loader className="org.apache.catalina.loader.VirtualWebappLoader" searchVirtualFirst="true" virtualClasspath="${xnat.home}/plugins/*.jar"/>

Save the file and close your editor.
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.2.war META-INF/context.xml
```
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:

Tomcat 7.0-compatible context.xml

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>

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

Monitoring and troubleshooting

The primary tool for monitoring and troubleshooting your XNAT deployment in Tomcat 7.0 is through log files. XNAT itself generates log files in the directory logs under the ${xnat.home} folder, but sometimes (for example, the system is misconfigured and XNAT doesn't start up enough to start its own logging system) you'll need to check the Tomcat log files to understand what's happening. The location of the Tomcat log files depends on how and where you've deployed Tomcat:

On most Linux or similar distributions, you can find the logs for Tomcat 7.0 in the folder /var/log/tomcat7 (sometimes the version is omitted, so you can also check /var/log/tomcat)
If you deployed Tomcat 7.0 manually, e.g. from a tarball or zip archive, the log files are usually located in logs right under the main Tomcat directory

There are three files that may contain relevant messages:

catalina.out captures the standard output stream from Tomcat. Note that newer versions or certain distributions of Tomcat may not generate catalina.out: if you don't see it, check the other log files.
catalina.yyyy-mm-dd.log is the primary Tomcat service log.
localhost.yyyy-mm-dd.log is the primary host log.

The Tomcat service and host definitions are set in the Tomcat configuration files and are described in the Apache Tomcat 9 Configuration Reference:

A handy way to reference the current file for file names that include a date is to use command substitution to inject the date:

CODE

$ tail -f /var/log/tomcat/catalina.$(date -I).log

Note that the OS X version of date does not support the -I parameter. There you can substitute date "+%Y-%m-%d" for date -I.