Setting Up and Updating XNAT

This page is intended only to document the usage of the setup and update scripts and is not intended to be in-depth documentation on installing and configuring XNAT. For information on installing XNAT, refer to the installation documentation.

XNAT is different from many modern Web applications in that it has two separate "build phases". It starts with a default set of source materials (Java code, Velocity templates, JavaScript, CSS, images, data-type schema, etc.), mostly located in the plugin-resources folder. This source, along with build scripts and some other support files, is what constitutes the XNAT release code. Once you run the set up process, the builder goes to work:

  • The first build phase consists of copying much of the source material into the projects/project folder, where project is the value set for the property in your file. The projects/project folder is usually referred to as the project folder.
  • The second build phase consists of copying, compiling, and processing the data in your project folder and pushing the results into the deployments/project folder.

Scripting these build phases is the task of the setup and update scripts. These are located in the bin folder of your XNAT builder installation. There is also a quick deploy script that can be used to quickly push out changes to display elements that don't require a rebuild of code or database changes. Each of these scripts is described below.

1.6 Modules

Prior to 1.6, customizing XNAT required putting any custom files into the proper location in the project folder. For example, if you wanted to add a custom report screen, you would put the Velocity template into the projects/project/src/templates/screens folder. This can get messy when an XNAT installation has a number of different customizations, which all end up mixed in together. XNAT 1.6 supports the development of customizations in the form of modules. This lets you package each of your customizations—including Velocity templates, Java code, JavaScript, and anything else—into a single tidy package. See the documentation on module development for more information.

Setting Up

XNAT setup can only be used on a clean installation of XNAT. That is, setup can not have been run previously.

OK, this isn't completely true: setup can't be run if the folder deployments/project exists. You can delete the folder and re-run setup if you need to do so for some reason:

rm -r deployments

In production scenarios, you very rarely want to do this, but in a development environment you may want to try building from a clean environment at times to verify customizations you've created work properly in a clean installation.

To set up your XNAT installation, invoke the setup script. Which script you use depends on your environment:

  • In *nix environments—including Linux flavors such as Ubuntu, Debian, Centos, or Scientific Linux, as well as OS X—you would use bin/
  • In Windows, you would use bin\setup.bat

For simplicity, this documentation will use the shell script version of commands. Windows differs only in the path separator (i.e. '\' as opposed to '/') and script extension (i.e. ".bat" as opposed to ".sh").

So for a basic set-up process, run the following commands:

  1. Stop your Tomcat server.
  2. Change your current directory to your xnat_builder folder.
  3. Run the setup script:
  4. Copy the resulting war file into the webapps folder of your Tomcat installation.

You can push the application directly into Tomcat, avoiding step 3, by adding the -Ddeploy=true flag to your script invocation: bin/ -Ddeploy=true. This deploys the application into the webapps folder underneath the location indicated by the maven.appserver.home property in your file.

As noted previously, there's more to the setup process than the build script! You also need to initialize your database and bootstrap the security data. For a full description of this process, refer to the installation documentation.


XNAT update is used to re-build and re-deploy your XNAT installation to include any changes, additions or deletions of code or functionality. In opposition to the setup process, update can only be run on an XNAT installation that has had setup run on it.

To update your XNAT installation, invoke the update script:

  • For *nix: bin/
  • For Windows: bin\update.bat

As with the setup script, you can build with or without automated application deployment. To deploy automatically, just append the same -Ddeploy=true flag to the update script.

Updating the Database

Once you've updated your deployment, you'll also need to update your database if you've made any changes to your data-type schema (this is similar to the database initialization process for XNAT installation, but doesn't require prepopulation of the database):

  1. Make sure that your Tomcat server is stopped! Database changes can be disrupted if the Tomcat server has locks on any of the affected data or tables.
  2. From the XNAT builder folder, change to the folder deployments/project.
  3. Run the database update SQL script: psql -U user -d database -f sql/project-update.sql, where user is the database user, database is the database name, and project is your project name.

Once you've updated your database (if necessary) and re-deployed your application, you can restart Tomcat and access the application to verify your changes.

Quick Deploying

The full update process above is useful if you've made changes to your Java code or changes that affect your database schema, e.g. changes in a data type. However you'll often just make changes to some Velocity templates or graphics or something like that. In that case, the full update procedure is quite time consuming for no good reason. For this purpose, you can do one of two things:

  • Deploy your changes directly into the XNAT web application
  • Make your changes in your project folder and run the quick deploy templates script

As with setup and update, how you invoke the quick deploy templates script depends on your environment: bin/ for *nix and bin\quick-deploy-templates.bat for Windows.

Unlike setup and update, the quick deploy templates script does not have an option for deploying to the application installation in Tomcat's webapps folder: its entire raison d'être is to deploy to the application installation in Tomcat's webapps folder, so there's no use for this utility if you're only deploying through a war file.

As of the initial release of XNAT 1.6, the quick deploy templates script does not support updating from modules in your module repository. There is currently an improvement request in the XNAT issue tracking system for this enhancement.