Legacy "Quick Installation" Guide

This page provides a high-level guide to installing and configuring XNAT and the various prerequisites for running it. If you're familiar with installing applications in Tomcat and configuring services in your server environment, this guide includes just the basic steps required to get XNAT up and running. More details can be found in Comprehensive Installation.

This documentation refers to the CATALINA_OPTS variable when configuring Tomcat. You may find that your version of Tomcat doesn't recognize this variable when set in the Tomcat configuration file, e.g. /etc/default/tomcat9. In that case, you have two options:

• Replace references to CATALINA_OPTS with JAVA_OPTS
• Export CATALINA_OPTS in the Tomcat configuration file, either by adding export to the first reference export CATALINA_OPTS at the end of the configuration file

To install XNAT:

1. Install all prerequisites:
   • Java 8
   • Apache Tomcat 8.5 or later (XNAT recommends 9.0)
   • PostgreSQL 10 or later
2. Create XNAT's data folders: archive, build, cache, fileStore, ftp, inbox, and prearchive. These folders must be owned by the user that owns Tomcat. The standard XNAT practice is to put these folders in one location, usually named /data/xnat (or, if you have a custom Tomcat user, that user's name, e.g. /data/foo), so you end up with /data/xnat/archive, /data/xnat/ prearchive, and so on.

3. Create a PostgreSQL user and database for your XNAT installation:

   Creating XNAT PostgreSQL user and database

   BASH

   $ sudo su - postgres -c "createuser -D xnat"
   $ sudo su - postgres -c "createdb -O xnat xnat"
   $ sudo su - postgres -c "psql -c \"ALTER USER xnat WITH PASSWORD 'xnat'\""

   There are different ways to create users and databases, as well as manage how users access the databases. For some configurations, you may not need to set a password for the user at all. And as long as you are accessing the database from XNAT on the same server, you may not need to change any PostgreSQL configuration options at all. See Configuring PostgreSQL for XNAT for more information.

4. Create the XNAT home folder. This is where the XNAT service stores and accesses configuration files, logs, plugins, and temporary files. That means this folder must be writable by the Tomcat user. If you create a custom user, you can just use the home folder for this user as your XNAT home.
5. Configure the property xnat.home in your Tomcat configuration file as part of the options environment variable to indicate the location of the XNAT home folder you created in the previous step. The location of the Tomcat configuration file depends on the platform (in the paths below, N is 8 or 9, depending on your Tomcat version):
   • On Debian/Ubuntu it is /etc/default/tomcatN
   • On Fedora/Red Hat, including CentOS 6, it is /etc/tomcatN/tomcatN.conf

   • On CentOS 7.x,it is /etc/tomcat/tomcat.conf

6. Append the value for xnat.home to CATALINA_OPTS:

   Setting xnat.home

   BASH

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

7. Create four folders under the XNAT home folder: config,  logs, plugins, and work. As with the XNAT home folder, these must be writable by the Tomcat user.
8. In your newly created config folder, create the file xnat-conf.properties. You can use the default version of the xnat-conf.properties file as a starting point. Set the database and other properties to the appropriate values.

9. Download the latest release of the XNAT war to your server:

   Creating XNAT PostgreSQL user and database

   BASH

   $ curl -L -o xnat-web-1.8.0.war https://api.bitbucket.org/2.0/repositories/xnatdev/xnat-web/downloads/xnat-web-1.8.0.war

10. Copy the war file into the Tomcat webapps folder. The location of this folder depends on where Tomcat is installed:
    • /var/lib/tomcatN/webapps on Debian/Ubuntu-based systems
    • /usr/share/tomcatN/webapps on Fedora/Red Hat-based systems

    There is no need to restart the Tomcat service: when a war file is placed in the webapps folder, Tomcat automatically deploys the application to the context filename (if a file of the same name already exists, Tomcat will redeploy the application). That is, if you copy the war file in as xnat-web-1.8.0.war, your newly deployed XNAT application will be available at the URL http://server/xnat-web-1.8.0. If you'd like XNAT to be the root application, you should rename it to ROOT.war:

    Copying the XNAT war as the root application

    BASH

    $ cp xnat-web-1.8.0.war /var/lib/tomcat9/webapps/ROOT .war

    You can monitor the start-up progress of your Tomcat server through the Catalina start-up log. On most Linux platforms, you can use tail for this purpose:

    Monitoring Tomcat start-up

    BASH

    $ tail -f /var/log/tomcat9/catalina .out 

    You may need to use sudo if your user account doesn't have access to the folder or log file.

11. Enter the address of your XNAT server in a web browser, e.g. http://xnat.miskatonic.edu (if you haven't set up a front-end proxy like nginx, you'll need to append the default Tomcat listen port 8080, so the URL would be http://xnat.miskatonic.edu:8080). Wait for the login page to appear.
12. Log into XNAT with the username admin and password admin. You should be directed to the XNAT site setup page.
13. Enter all the required data in the site setup form and click the Save button at the bottom of the page.

If everything went well, you should now be logged into your new XNAT instance.