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.
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|
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.
|build||/data/xnat/build||This 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.
|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.
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/||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/||Location for all logs created by the web application. Useful for debugging purposes.|
|plugins/||The place to install XNAT plugin JAR files.|
|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.
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.
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.
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
- A folder for your XNAT instance in
If this is not the case, see this documentation on enabling your nginx proxy.
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.
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.
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.
Documentation for this topic is still in development
Scripting In XNAT
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
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:
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.