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.

• Backing up data
• Upgrading application
• Updating plugins
• Updating the legacy pipeline engine
• Troubleshooting

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:

1. Back up the deployed XNAT web application by copying the war file to your backup location.
2. Back up your database using pg_dump, pgAdmin, or other database tools: pg_dump -d xnat > xnat-backup.sql
3. 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 application

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

1. If Tomcat is running, shut it down.
2. Back up your current XNAT installation, as specified above.
3. Replace the existing XNAT war file with the upgraded version.
4. 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.
5. Start Tomcat.

Updating plugins

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.

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.

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:

1. Log into your upgraded XNAT with an administrator account.
2. Click the Administer->Site Administration menu command.
3. Select the File System tab.
4. Enter the new location for your pipeline engine in the Pipeline Path text box.
5. 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 your XNAT webapp 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 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>

• You can also try checking your logs. It is possible that it is correctly picking up on your plugin code, but there is some coding 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.