Understanding the Components of XNAT

This document is meant to be an introduction to the logical architecture of XNAT – how it is set up, how it manages data and permissions, and how it allows you to customize it. This is meant for an XNAT Administrator audience, who should be comfortable working with the UI and administering the XNAT web server via the command line. There is greater depth to be found in the XNAT Developer Documentation.

Overview of XNAT Components

A standard XNAT installation contains two WAR files:

The XNAT web application WAR file, or "The XNAT Stack."
The Pipeline Engine

The XNAT Stack consists of a series of components that run in an Apache Tomcat 7 web server, as visualized below.

Insert Diagram Here

XNAT Webapp File Structure

XNAT File System Directories

There are dedicated directories in place in the XNAT web app that are used for file storage. The locations of these can be customized in the UI in your first time configuration, which can be useful if you intend on handling large amounts of data. It is possible, but not recommended, to change these locations at a later date.

Folder Name	Standard Location	Purpose
archive	/data/xnat/archive	The XNAT Archive is the permanent storage location for all XNAT files, such as uploaded DICOM files or project resource files. All files in this folder are catalogued in the XNAT web application, and tracked in the XNAT audit trail. For any non-clinical XNAT, take steps to prevent files with personal health information (PHI) from being stored in this location.
build	/data/xnat/build	This path is currently unused, but is reserved for potential future enhancements to the build process.
cache	/data/xnat/cache	The XNAT user cache is a place where XNAT can store user-specific files. These are often temporary files. When users or processes mark a file for deletion, XNAT does not actually delete the file. Instead, it is sent to the `cache/deleted` directory. It is a good idea to monitor usage of this folder periodically, as it can retain large amounts of unneeded data.
ftp	/data/xnat/ftp	The ftp location is the place where the XNAT FTP Server would write files to. This path can be set to a dummy value if you aren't setting up the FTP Server.
prearchive	/data/xnat/prearchive	The XNAT Prearchive is an interim file storage area separate from the XNAT Archive, where uploaded files can be safely reviewed for PHI. It is common for ongoing studies to upload image sessions to the Prearchive rather than directly to the archive.

For more information about advanced file system management, see the XNAT IT Operations documentation.

XNAT_Home Directory

Each XNAT installation has, in its folder structure, a folder known as XNAT_HOME. In a typical installation, this is located at /data/xnat/home. XNAT installation will create a system user named xnat that has permission to read, write and execute files in this directory. Many customizations that you make, such as adding plugins or enabling additional configurations, will take place in the subfolders located here:

Folder Name	Standard Location	Purpose
configs/	`/data/xnat/home/configs`	Allows you to store additional configurations that will be used directly by XNAT. Note: configurations in this folder will overwrite any configurations specified in plugins.
logs/	`/data/xnat/home/logs`	Location for all logs created by the web application. Useful for debugging purposes.
plugins/	`/data/xnat/home/plugins`	The place to install XNAT plugin JAR files.
work/	`/data/xnat/home/work`	This is a working directory which can be used by multiple processes.

Tomcat 7 Web Server

The XNAT web app runs on a Tomcat web server. XNAT 1.7 uses Tomcat 7. We do not recommend using Tomcat 8 yet.

Tomcat Settings

If you need to change your Tomcat configuration, those files are located at: /etc/default/tomcat7. This is useful for setting JAVA_OPTS settings to ensure that your application runs smoothly.

Tomcat Folders

The xnat file system user should have full ownership of each of these folders to ensure proper web app functioning.

/var/lib/tomcat7
/etc/tomcat7
/var/log/tomcat7
/var/cache/tomcat7

UI Template File Location

By default, the XNAT web application is located at /var/lib/tomcat7/webapps/ROOT. All templates, scripts, style and image files used in the XNAT UI are located here. This will be the file path you will want to set up for SCP / FTP access, if you wish to modify any of those files.

nginx Proxy

For a variety of reasons, it's a very good idea to configure a front-end proxy for your Tomcat server (if you want to understand why, ask a member of the XNAT team or have a look at the docs about configuring nginx as a reverse proxy). The xnatstack box is configured with the nginx service for this purpose.

If this is set up properly, you should have the following in your file system:

A file for your XNAT instance in /etc/nginx/sites-available
A folder for your XNAT instance in /etc/nginx/sites-enabled

If this is not the case, see this documentation on enabling your nginx proxy.

Databases

PostgreSQL Database

XNAT uses the PostgreSQL database to store all of its persistent data that's not stored in files on the local storage device. The XNAT web application requires a dedicated user and database to be set up. This is a fairly straightforward process.

There are many tools that you can use to access the database, including Web-based and application clients. Tools that run remotely, such as pgAdmin3 , usually require more configuration. The documentation for pgAdmin3 describes how to set this up properly.

The XNAT Search engine queries this PostgreSQL database, and it is possible to run advanced SQL queries directly against this database to perform advanced reporting tasks.

Hibernate Database

In addition to the PostgreSQL database, XNAT uses a Hibernate database for storage of more mutable data, such as site config and project config settings. XNAT plugins can also make use of this database.

XNAT Security

Documentation for this topic is still in development

Scripting In XNAT

XNAT supports scripting in Groovy, Python, and JavaScript. There is a script console in the Administration Pages, but it is advised to tread very carefully in that console unless you have developer-level knowledge of XNAT's inner workings.

XNAT API

As of XNAT 1.7, there are two versions of API coexisting within the XNAT application: the legacy XNAT REST API, and the new-generation XAPI. All XNAT API are documented here: XNAT REST API Directory.

Adding On To XNAT

Adding Pipelines to XNAT

By default, the pipeline engine is located at /data/xnat/pipeline. This is also commonly referred to in documentation as the PIPELINE_HOME directory. All pipelines installed here will be visible to the XNAT web application under Administer > Pipelines. See Installing Pipelines in XNAT.

Installing XNAT Plugins

The full documentation for installing and managing XNAT plugins is here: Deploying Plugins in XNAT. As referenced above, the standard location of your plugins folder is here: /data/xnat/home/plugins.

For more on working with or developing new XNAT plugins, see this guide: Working with XNAT Plugins.

Adding XNAT Configurations

Admins and developers for earlier versions of XNAT will be familiar with managing configuration files. To a large extent, the XNAT 1.7 WAR-only build and plugin architecture should radically reduce the amount of time you spend in this area. However, should you need to add or manage XNAT configurations, the default location for these files is here: /data/xnat/home/configs

Any setting that is specified in a config file will overwrite any version of that setting that is specified in a plugin. This can cause conflicts and confusion if not properly managed.