There are a couple different update methodologies you can pursue:
Previous versions of XNAT required that all customizations be placed into the projects folder under your XNAT builder folder. This documentation said that you should copy that folder over from your existing XNAT builder into the projects of your new XNAT builder when upgrading. This step has changed and is documented in more detail below.
Updates and Upgrades
New Release / New Database
Follow the steps in the installation guide to complete the installation. If you've made modifications to your projects directory, perform the following steps after Step 4 in the installation guide.
New Release / Old Database
If you haven't written custom code for XNAT, or your only customizations are in xnat/projects:
- If your Tomcat server is running, shut it down.
- Back up your current XNAT installation.
- Extract or download the copy of your new version of XNAT into a different location from your previous one.
- Configure build.properties in the new release, using your old build.properties as a guide.
- Run the bin/setup.sh script to initialize your new release. This is the same as step 4 in the installation guide (also, be aware of any breaking changes). Note that, for this step, you should run bin/setup.sh without the -Ddeploy=true option, even if you normally build or update with that option turned on.
- If you have any project customizations from your previous installation, migrate them to the new version.
- Delete the old XNAT web application from your Tomcat installation. If you've installed by war file, you'll want to make sure you delete both the war and the exploded application folder if it exists.
- Run the bin/update.sh script. Here you can specify the -Ddeploy=true option if you normally use that method for deploying your application.
Run the deployments/project/sql/project-update.sql database update script. For a project named 'xnat':
If you've modified the services.properties file–for example, to add an LDAP authentication repository–you should compare your version of this file with the updated version. The primary concern is not values that are different–those would mostly be due to configuration-specific differences–but properties that have been added to the core XNAT development version that won't be present in your customized copy of services.properties. You will need to merge any changes between the two files into your deployed XNAT web application.
If you've customized xnat_builder (assuming you forked it at some point in the past):
- Take a backup.
- Pull xnat_builder from BitBucket and merge with your changes.
Another option: Use
pgdump to duplicate your database, and upgrade using that copied database. This will allow you to leave your old site up and running until you are comfortable that your upgrade was successful. To do this, you should modify the database connection parameters in build.properties after you copy it to the new installation.
If you've built your upgraded XNAT in a different folder from your previous version and use the standard pipeline engine installed under the xnat_builder folder, or if you've installed your upgraded pipeline engine in a folder separate from your xnat_builder but in different folder from your previous version, you need to make sure you change the configured location of your pipeline in your upgraded XNAT installation before running any pipelines, including archiving new sessions, which implicitly invokes the auto-run pipeline:
- Log into your upgraded XNAT with an administrator account.
- Click the Administer->Configuration menu command.
- Select the File System tab.
- Enter the new location for your pipeline engine in the Pipeline Installation Location 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.
Migrating XNAT Customizations During XNAT Upgrades
Migrating the projects folder is the "traditional" (for lack of a better term) method of carrying over customizations from one version to the next. This is problematic, though, since things that have changed in the meantime may not be updated in the projects folder, meaning that you'll be getting old code instead of the new release.
Optimally, you'd manage this by having all of your customization code in modules. If you already have all of your XNAT customizations in modules, you can simply delete the projects and deployments folders and re-run setup and update (this ordering is necessary since update generates the SQL script to update database based on any changes in the data-type schema). This generates your projects and deployments folders again on the setup and creates your database migration script on the the update. Both scripts will process any modules you have in the specified module repo folder.
If you don't have all of your XNAT customization code in modules, you can keep your existing projects folder and copy over only those files that are part of your own customizations. This may be easier said than done, especially if you've worked on lots of little bits of code over a period of years. In that case, you can perform a diff of your projects folder with a vanilla XNAT projects folder from your previous release. To get the vanilla projects folder for this purpose, you could download, for example, the 22.214.171.124 builder from:
Run setup on this without the deploy flag set to true (i.e. just bin/setup.sh). You should be able then to diff your projects folder with the newly generated one and get a good idea of what's changed.
Take a Backup
- Backup your database (using pgdump or pgAdminIII)
- Backup your xnat webapp by making a copy of XNAT_HOME\deployments\xnat\target\xnat.war (if it's not there, run the update script w/o the deploy=true flag).
Migrating Pre-1.6 Scan Times for XNAT 1.6.x
If you are upgrading, you should run the deployments/project/sql/project-update.sql script before running the scan-time migration script.
If you have made any customizations, either in xnat_builder or in your own projects, and any of your customized files use scan time, you should modify those files manually. Scan time was previously stored in:
No other modalities had a scan time attribute. The replacement is for these separate scan times is xnat:imageScanData/startTime . To migrate the old scan time attributes to use the new start time attribute, we've provided a migration script that only needs to be run once when migrating from a pre-1.6 database. To perform this migration:
- Shut down Tomcat if it's running.
- Run the scan-time update script:
psql -U postgres -d xnat -f scan_time_update.sql
- Restart Tomcat.