Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 1.7 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 NameStandard LocationPurpose

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/buildThis path is currently unused, but is reserved for potential future enhancements to the build process.

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/ftpThe 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/prearchiveThe 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 NameStandard LocationPurpose
configs//data/xnat/home/configsAllows 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/logsLocation for all logs created by the web application. Useful for debugging purposes.
plugins//data/xnat/home/pluginsThe place to install XNAT plugin JAR files.
work//data/xnat/home/workThis 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.


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.



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



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.




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


Installing XNAT Plugins

The full documentation for installing and managing XNAT plugins is here: Deploying Plugins in XNAT 1.7. As referenced above, the standard location of your plugins folder is here: /data/xnat/home/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.