XNAT Installation Guide

If you are upgrading an existing XNAT installation, please see How to Upgrade XNAT.

This guide leads you step by step through the process of manually installing and configuring the components of XNAT. If you are looking for a "quick" path to getting an XNAT instance up and running, we recommend using one of the following prepackaged XNAT installations:

Step 1: Install Prerequisites

1: Start with a compatible server OS.

XNAT can be installed on any flavor of Linux OS or modern Unix-based Mac OS. Running XNAT on Windows is no longer supported and recent versions of XNAT have not been tested on Windows. We recommend either using a different operating system or running XNAT in a Vagrant virtual machine.

Tomcat 9 is not available on RHEL 8.0, Ubuntu 24.04, and later versions. You can install Tomcat 9.0 on these and similar operating systems manually, but XNAT can not provide documentation or support for doing so. There are many guides available on the topic, for example here.

Tomcat 9.0 is available for installation in the default configuration for Ubuntu 22.04 and Debian 10. These may not provide a suitable version of PostgreSQL, but you can configure the package manager to include later versions.

Note that CentOS and Scientific Linux have been discontinued and deprecated. XNAT provides no support or validation for these platforms.

2: Install the core XNAT dependencies

Java 21 JRE or JDK (XNAT 1.10.0 and later will not run on earlier versions of Java and has not been tested on releases newer than Java 21)
Apache Tomcat 9.0 (due to changes in Java package naming, XNAT 1.10.0 will not currently run on Tomcat 10 or later)
PostgreSQL 16, 17, or 18 (XNAT has worked with versions of PostgreSQL as early as 12, but 1.10.0 has only been validated against versions 16 through 18)

In addition to these, there are other optional components you may wish to install, such as setting up a reverse proxy such as nginx, haproxy, or squid proxy. See Prerequisites for Installing XNAT for detailed installation instructions.

Step 2: Configure PostgreSQL

Configuring PostgreSQL is big topic, much of which is outside the scope of using it with XNAT. This page specifically addresses configuring access and security for the connection between XNAT and PostgreSQL. Other issues like tuning and improving performance may be addressed later.

The required steps for configuring PostgreSQL are located here: Configuring PostgreSQL for XNAT, and are summarized as follows:

1: Create XNAT's database user

2: Configuring database access

3: Configuring TCP/IP Listeners

4: (Optional) Managing database access by user and host

Step 3: Set Up XNAT_HOME and the File System Structure

A series of file system paths must be set up on Tomcat and owned by the Tomcat service user. We recommend changing the Tomcat service user and group to something relevant to your XNAT installation, e.g. xnat, though this isn't strictly necessary.

1: (Optional) Set the Tomcat service user and group

Locate the primary Tomcat configuration file. This location will depend on your server OS.

We use the plain name tomcat in the notes below. Depending on the OS and version, you may find these folders are named tomcat9.

For Debian and Ubuntu systems, this is usually located in /etc/default/tomcat.
For Fedora, Red Hat, CentOS, and similar systems, this is usually located in /etc/tomcat/tomcat.conf, but may be in /usr/share/tomcat/conf/tomcat.conf (newer versions of these operating systems don't provide installations for Tomcat later than version 7).
OS X doesn't have the same standard method of configuring properties for Tomcat as a service. Generally, you can create a file in the bin folder for your Tomcat installation named setenv.sh. You should also make the file executable with the command chmod +x setenv.sh . You can modify this file in the same way as the configuration files for the Linux platforms.
For manual installs of Tomcat 9, the location of the Tomcat configuration files depends on where you installed Tomcat itself.

You may also need to modify the unit file for the Tomcat service definition. This is usually located in /etc/systemd/system/tomcat.service. If you modify the unit file, you'll need to reload the configuration with the following command:

BASH

sudo systemctl daemon-reload

Modify your configuration so that the Tomcat user and group properties are set to your preferred values. For Tomcat 9, this will be in the primary Tomcat configuration file:

BASH

# Run Tomcat as this user ID. Not setting this or leaving it blank will use the
# default of tomcat.
TOMCAT_USER=xnat

# Run Tomcat as this group ID. Not setting this or leaving it blank will use
# the default of tomcat.
TOMCAT_GROUP=xnat

When the user and group are specified in the service definition, you'll need to modify the unit file. The code below shows the security configuration from the Tomcat 9 unit file on Ubuntu 22.04:

BASH

User=xnat
Group=xnat
PrivateTmp=yes
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=true
CacheDirectory=tomcat
CacheDirectoryMode=750
ProtectSystem=strict
ReadWritePaths=/etc/tomcat/Catalina/
ReadWritePaths=/var/lib/tomcat/webapps/
ReadWritePaths=/var/log/tomcat/
ReadWritePaths=/opt/xnat/

Note that the configuration above, in addition to changing the values for User and Group, also adds an entry for ReadWritePaths with the value /opt/xnat/. This is necessary so that the Tomcat process, running as the xnat user, can read and write to folders and files under the specified directory. If you break the XNAT folders into different root directories, you'll need to add similar entries for each root folder. For example, if you set the XNAT home folder to /home/xnat and the storage folder (archive, prearchive, etc.) in /mnt/storage/xnat, you'd need to add the following entries to the unit file:

BASH

ReadWritePaths=/home/xnat/
ReadWritePaths=/mnt/storage/xnat/

Note also the trailing '/' character. This allows the user to create and write to folders and files underneath the specified folder.

One virtue of creating a new service user is that this user's home (~/) folder can be treated as the XNAT_HOME directory, which we will set up in the next step. For now, while we are in the Tomcat configuration file, we must define the location of the XNAT_HOME directory. Scroll down to the CATALINA_OPTS section of the config file and enter:

CODE

CATALINA_OPTS="${CATALINA_OPTS} -Dxnat.home=/opt/xnat/home"

You may want to enter other Tomcat configurations here as desired, such as setting other JVM options and installing the Tomcat manager application. Detailed instructions can be found in Prerequisites for Installing XNAT

After changing the Tomcat service user, you must give this user ownership of the Tomcat directories.

BASH

$ chown -RH --dereference xnat.xnat /var/lib/tomcat
$ chown --no-dereference xnat.xnat /var/lib/tomcat/*

2: Create the XNAT_HOME set of folders

The XNAT web application will look in XNAT_HOME for key configuration resources which will be used at system startup, as well as for capturing XNAT-specific system logs. See Understanding the Components of XNAT for a detailed description of the XNAT_HOME folder structure and contents.

Create folders for these components now.

BASH

$ mkdir -p /opt/xnat/home/config
$ mkdir /opt/xnat/home/logs
$ mkdir /opt/xnat/home/plugins
$ mkdir /opt/xnat/home/work

3: Create the XNAT data folders

These folders sit outside XNAT_HOME and are used for data file storage. See Understanding the Components of XNAT for a detailed description of the XNAT file system folder structure and contents.

Create these folders as well.

BASH

$ mkdir /opt/xnat/archive
$ mkdir /opt/xnat/build
$ mkdir /opt/xnat/cache
$ mkdir /opt/xnat/fileStore
$ mkdir /opt/xnat/ftp
$ mkdir /opt/xnat/inbox
$ mkdir /opt/xnat/prearchive

4: Grant ownership to the Tomcat service user

If you set a new service user in step 1, use the name of that user, but if using the default Tomcat service user tomcat then use that:

BASH

$ chown -R tomcat:tomcat /opt/xnat # For the default Tomcat service user
$ chown -R xnat:xnat /opt/xnat     # For a custom service user named xnat

Step 4: Configure XNAT for Initial Startup

Create the XNAT configuration file xnat-conf.properties in the folder ${xnat.home}/config. This file is used for initializing the database connection and setting the properties for XNAT's Hibernate configuration.

If you don't add the database connection and Hibernate properties, XNAT will use its own default properties, which are the same as those in the default version listed below.

1: Create the xnat-conf.properties file

BASH

$ touch /opt/xnat/home/config/xnat-conf.properties

2: Populate your configuration properties, using this sample as a starting point

Note the username and password for the PostgreSQL datasource must match what you used when configuring PostgreSQL earlier.

Sample XNAT configuration

JAVA

datasource.driver=org.postgresql.Driver
datasource.url=jdbc:postgresql://localhost/xnat
datasource.username=xnat
datasource.password=xnat
 
hibernate.dialect=org.hibernate.dialect.PostgreSQL9Dialect
hibernate.hbm2ddl.auto=update
hibernate.show_sql=false
hibernate.cache.use_second_level_cache=true
hibernate.cache.use_query_cache=true

3: Don't worry about importing datatypes or file configurations.

Unlike XNAT 1.6 and earlier, XNAT versions 1.8 and later do not require a separate step to import core or custom data types. This removes the need to run any setup, update, or SQL scripts prior to starting XNAT. All database schema are created and initialized upon application startup.

Accordingly, there is no need to configure any files with the location of your XNAT data folders. These are also initialized on application startup.

Step 5: Install the XNAT Web Application

The XNAT web application is distributed as a "war file", or "web application archive", which contains the entire XNAT application in a single bundle. There are a multiple ways to install XNAT itself, but the easiest is to simply deploy the XNAT war file. You can always retrieve the latest public XNAT war at https://download.xnat.org/

1: Stop Tomcat if it is running.

BASH

$ sudo systemctl stop tomcat.service

2: From your local system, upload the XNAT war file to the Tomcat webapps directory

When you upload the distributed war file to Tomcat, you will want to rename the war to match the server path where you want your application to be accessed. For example, if you wanted to reach your XNAT at https://{server}/xnat, you would rename the file to "xnat.war". If you want XNAT to be available at your server root path, rename the file "ROOT.war"

BASH

$ scp xnat-web-1.10.0.war xnat@{server}:/var/lib/tomcat/webapps/ROOT.war

You may need to use scp to copy the war file up to a temporary location and then move it into place in Tomcat’s webapps folder. Once installed in the webapps folder, you should name the war file to ROOT.war or the file name minus extension will be used as the application’s context path, i.e. a path appended to the server URL. For example, if you are running Tomcat on localhost and copy the war file to xnat.war, XNAT will be accessible at http://localhost/xnat.

Note that the web application file (war file) must be owned by the Tomcat service user.

3: (Optional) Manually explode the war file to a directory

On server startup, Tomcat will automatically extract your war file to a directory matching the name of the war file. If you wanted to manually extract the war file to a different directory, you can. For example, this would take an uploaded file named "xnat.war" and extract its contents to the ROOT directory.

BASH

$ cd /var/lib/tomcat/webapps
$ mkdir ROOT
$ cd ROOT
$ jar -xvf ../xnat.war

4: Start Tomcat and monitor Catalina until it starts up successfully

BASH

$ sudo systemctl start tomcat.service
$ tail -f /var/log/tomcat/catalina.out

The catalina.out system log file will display messages from Tomcat while it attempts to launch your XNAT webapp. Assuming it is successful (i.e. no SEVERE errors are logged), you will see a message like this:

BASH

SOURCE: /var/lib/tomcat/webapps/ROOT/
Database up to date.
Mar 08, 2021 11:59:14 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deployment of web application archive /var/lib/tomcat/webapps/ROOT.war has finished in 91,125 ms
Mar 08, 2021 11:59:14 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Mar 08, 2021 11:59:14 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 92397 ms

Step 6: Set Up Your XNAT

If this is the first time your XNAT has started up, you will be taken to the first-time setup screen to confirm or enable key startup settings. See XNAT Setup - First Time Configuration for more details on these settings.

1: Navigate to your XNAT's web URL in a browser

2: Log in using admin credentials

If this is your first time logging in, these credentials are "admin:admin".

After first-time setup, and before creating any other user accounts, go to your admin user settings and change the default password. Also, if you are configuring a production deployment of XNAT, we strongly recommend that you create a new personal administrator account and disable the default admin account altogether.

3: Complete the first-time setup

Congratulations! You now have a running XNAT system!

Next Steps: Extending XNAT

You can extend XNAT through the use of plugins. Plugins are simply jar files that contain a mix of datatype schema, Velocity templates, JavaScript files, JSP pages, compiled Java classes, and more. See Deploying Plugins in XNAT for installation instructions.

Core XNAT plugins to consider installing:

In previous versions of XNAT, you had to configure any new datatypes you added to XNAT. XNAT automatically configures new datatypes and makes them available for immediate use. You still may want to configure any new datatypes just to set the readable names and check the security settings for it, but you don't need to do that just to create new instances of your datatypes.