How to Upgrade XNAT

This page describes how to upgrade your XNAT installation to the latest version of XNAT. This guidance includes three basic steps, plus troubleshooting at the end.

If you are upgrading a system using XNAT 1.6 or earlier, please refer to XNAT 1.6 and Earlier Upgrade Guide.

The process of upgrading from XNAT 1.7.x or 1.8.x to the latest version of XNAT 1.9.x is almost identical. Any differences are called out explicitly in the documentation below.

Backing up data

A thorough backup of your XNAT installation is a valuable safeguard not only when upgrading XNAT, but also in the event of a system crash, power outage, or other unforeseen event that could cause the loss of valuable data. To back up your XNAT:

Back up the deployed XNAT web application by copying the war file to your backup location. If the war is named ROOT.war or xnat.war or something similar, you should copy it using a name that indicates the version, e.g. if you're upgrading from XNAT 1.8.9, do something like: cp /var/lib/tomcat/webapps/ROOT.war xnat-web-1.8.9.war
Back up your database using pg_dump, pgAdmin, or other database tools: pg_dump -d xnat > xnat-backup.sql
Optionally, if you have the space or technical ability, backing up or snapshotting your data archive folder provides an extra level of security for your data assets.

Upgrading the application

Upgrading XNAT to the latest release is a matter of replacing the XNAT war file:

If Tomcat is running, shut it down.
Back up your current XNAT installation, as specified above.
Replace the existing XNAT war file with the upgraded version: cp xnat-web-1.9.0.war /var/lib/tomcat/webapps/ROOT.war
If there is a folder in the webapps folder containing the "exploded" web application (it will have the same name as the war file, just without the .war extension), delete it. For example, if your war file is named ROOT.war the exploded application folder is named ROOT: rm -rf /var/lib/tomcat/webapps/ROOT
Replace any plugins that also need to be upgraded (see the section below for more information about plugin upgrades).
Start Tomcat.

Updating plugins

Dependency upgrades

The changes in XNAT 1.9 include many changes in its dependencies, including significant updates to Spring Framework, Spring Security, Hibernate, and caching libraries (see the XNAT 1.9.0 Release Notes. In addition, a number of dependencies–including older versions of the Ehcache libraries–have been removed. Any plugins that referenced these dependencies may require updates to work properly with XNAT 1.9.x. You should test your plugins with XNAT 1.9.x in a test or development instance of XNAT before attempting to upgrade any production instances.

See: Updating Plugins for Changes in XNAT Dependencies

The core suite of XNAT plugins – including Container Service, DICOM Query Retrieve, and the XNAT-OHIF Viewer – have 1.9-compatible upgrades available, or have been tested for compatibility with XNAT 1.9. These are also described in the XNAT 1.9.0 Release Notes.

When you are customizing elements of the XNAT code, we strongly recommend using plugins to manage these customizations to speed your upgrade path. Any customizations that you have made directly to the webapp will be harder to track down and recreate. XNAT is configured to look first in plugins for content, then to look in the web application. This should work well for all content that can reside under META-INF/resources, as well as any content you have added to XNAT.

One other thing to keep in mind is that if the files you customized have changed in XNAT, the upgraded XNAT web application may not work correctly without these changes. If your customization was simple, you may want to start with the version of the files from the latest version of XNAT, make your customization to it, and then put it in a plugin. If you don't remember what you changed, you can look up the source code for the version of XNAT you based your customization on in the xnat-web repo by selecting the right version tag in the Bitbucket UI.

After you have installed XNAT and updated your customization plugins, you can simply put these plugins in your plugins directory and restart Tomcat. Your XNAT should then be using all of your customizations.

You can watch the server logs to monitor the progress of the database update and migration. Tomcat's catalina.log and XNAT's sql.log tend to offer entry points into any errors that may occur:

CODE

$ tail -f /var/log/tomcat/catalina.out
$ tail -f ~/logs/sql.log

If anything goes wrong during the upgrade process, you can dump the modified database and new web application, then restore your database and earlier version of XNAT. Please preserve all log and configuration files and contact us with as much information as possible on what happened.

Updating the legacy pipeline engine

Follow the instructions for building and installing the Pipeline Engine, using the latest version of code, if you are using the legacy pipeline engine with your XNAT.

As of the XNAT 1.9.0 release, XNAT no longer includes code to integrate with the legacy pipeline engine.

If you use the legacy pipeline engine for data processing, you'll need to install the XNAT Pipeline Engine plugin. Documentation for this plugin can be found here.

As of the XNAT 1.8.0 release, XNAT no longer requires the legacy pipeline engine.

Previously, the pipeline engine was required because XNAT relied on it to generate snapshot images for newly uploaded image sessions. XNAT now generates snapshot images internally on demand. If you only used the pipeline engine for the default AutoRun pipeline and snapshot image generation, you can remove the pipeline engine.

If your XNAT performs off-board processing tasks like NIFTI or BIDS translation, consider switching to using the XNAT Container Service instead.

If you've installed the XNAT pipeline engine in a different location from the previous version, you must change the location configured in XNAT for the pipeline engine before running any pipelines. If you have the Autorun pipeline enabled, then this means you must update this path before uploading new image data. Follow these steps:

Log into your upgraded XNAT with an administrator account.
Click the Administer->Site Administration menu command.
Select the File System tab.
Enter the new location for your pipeline engine in the Pipeline Path text box.
Click the Save button.

If you don't make this change, you may see all kinds of weird errors, including failing to generate snapshots of your newly archived sessions, verbose messages in error logs, etc.

Troubleshooting

Plugins Not Working

If the code you have in your plugins does not seem to be taking effect, there could be several possible explanations. Here are some of the things you should check:

Make sure there is a directory named plugins directly under the xnat.home directory and that xnat.home is defined for Tomcat as explained in the installation instructions.
Make sure that the owner of your plugins directory and the owner of each plugin file matches the owner of the XNAT web application directory and that you have sufficient file permissions
Make sure your plugins are correctly structured. It is easy to accidentally create a jar of the directory that contains your plugin's code instead of building a jar using the plugin's gradle builder. If you open the jar for your plugin, there should be a META-INF directory at the top level of it.
Make sure the location of any content that is to be loaded at initialization by Spring (e.g. @Service classes) are indicated in the @ComponentScan annotation definition of your @XnatPlugin configuration class.
Similarly, make sure that the location (package) of any Hibernate entities you have added are included in the entityPackages attribute of your @XnatPlugin annotation.

Look at the server.xml configuration for your Tomcat installation and see if you have a <Context> path section. This may be preventing Tomcat from picking up your plugins. If you have a section like this, remove it:

XML

<Context path="" docBase="/var/lib/tomcat/webapps/xnat" >
	<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"                        		
		factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
	<Manager pathname=""/>
</Context>

You can also try checking the XNAT and Tomcat logs. It is possible that it is correctly picking up on your plugin code, but there is a code or configuration error that is preventing it from working properly. See if there is an error message in one of the log files that is related to your plugin code.

Database Error

In XNAT, most database updates happen automatically and run upon Tomcat startup. New tables will be generated based on schema files that you add in your plugins and new columns will be generated for fields you add to your schema. Additionally, tables will be generated for hibernate entities you define in your plugins and will be updated as you add additional elements to your class. This process works well for customizations that add database tables and columns, but can fail when the data types of existing fields are changed.

While new tables and columns can be added to the database for new versions of XNAT, changes to existing database columns are generally quite rare. When there have been changes to existing columns or existing database contents, initializers will be written to perform the database updates necessary to assist your migration.

If you are experiencing a database error after upgrading to XNAT and have added one or more datatype plugins to XNAT, you could see database errors if the type of a field has changed. You may need to check with the datatype plugin developer to see if a database update needs to be performed.

If the problem is in a database view, you may be able to eliminate the problem simply by deleting the problem views and restarting Tomcat. Any missing views will then be regenerated. If the problem is in a table, you may need to create and run a SQL query to update your existing table and copy data from the old version of the column to the new version.