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 to the latest version of XNAT 1.8.x is almost identical. Any differences are called out explicitly in the documentation below.
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:
pg_dump -d xnat > xnat-backup.sql
Upgrading XNAT to the latest release is a matter of replacing the XNAT war file:
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 webapp 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:
$ tail -f /var/log/tomcat7/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.
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.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:
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.
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:
Look at your server.xml 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:
<Context path="" docBase="/var/lib/tomcat7/webapps/xnat" >
<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
<Manager pathname=""/>
</Context>
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.
Upgrading a database that has XNAT ML Beta data on it will require updates to the database tables. See Migrating XNAT ML data from Beta to Production
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.