XNAT Docs Index

Related Pages

 Click here to expand...

This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at https://xnat.org/documentation

Skip to end of metadata
Go to start of metadata

If you are upgrading an existing XNAT installation, including a completely new code installation but with an existing database and data archive, please see the XNAT upgrade documentation instead of this page.

Step-by-Step Guide to Installing XNAT

This tutorial walks through an installation of XNAT.  It is recommended that prospective users/developers complete this tutorial.

 Please review and install the prerequisites for XNAT installation before proceeding with this tutorial. As of the 1.6.4 release, XNAT is not compatible with the following applications:

  • Java 8 or later: You should use the latest version of Java 7 that is available for your platform, but XNAT will not run properly under Java 8.
  • Tomcat 8 or later: You should use the latest version of Tomcat 7 that is available for your platform, but XNAT will not run properly under Tomcat 8.


1. Get the Source

Download the distribution and extract locally.  The extracted directory will include all of the files needed to generate, deploy and execute your XNAT application(s). There are three directories in this project which will be of direct interest to you (the projects and deployments directories will be created later in step 4).

  • bin directory:
    This is the location where the executable files for your application will be generated and placed. It is recommended that you add the 'bin' directory to your 'path' environmental variable (though this may be problematic if you have multiple XNAT installations).
  • projects directory:
    XNAT will generate a folder in this directory for each of your projects. When you make customizations to your XNAT project, you will modify the files in this directory. These modifications will then be processed by the setup or update script.
  • deployments directory:
    XNAT will generate a folder in this directory for each of your projects. It stores the settings for your command line tools. It will also be used to generate your web application via the setup or update command.

UNIX Users

We strongly recommend that the directory into which you extract your XNAT distribution be owned by the same user account that executes Tomcat. That same user should also own the directories for your actual data as defined in step 4 (archive, prearchive, cache, and so on). Lastly, you should switch to that user when running the build and update scripts. This ensures that all application and data files and folders are accessible by Tomcat.

You can leave Tomcat to run as the default user tomcat or you can create a new user, set Tomcat to run under that user account (how this is accomplished really depends on your particular OS), and change ownership of the Tomcat installation itself to that user. The latter configuration is how the XNAT development and IT teams generally set up XNAT installations.

Windows Users

For easier setup, install XNAT in a directory which does not include spaces in its name or in any of its parents' names. It's also advisable to install your Tomcat server in a folder that is not located under the C:\Program Files or C:\Program Files (x86) folder structure. Windows 7 and most of the Windows server operating systems have very restrictive security policies in those folders that can cause lots of weird permissions errors and unpredictable behavior.

2. PostgreSQL Configuration

PostgreSQL should be completly installed and tested according to the PostgreSQL documentation before proceeding.  To guarantee proper installation of PostgreSQL, all of the installation steps should be performed, including the creation of a test database.  XNAT has been tested with PostgreSQL version of 8.4 and newer.  XNAT 1.6 supports 9.1+.

If you have trouble accessing your PostgreSQL database:

  • Review the listen_address property in your installation's postgresql.conf file located in the data directory. Some installations require this property to be un-commented before the database will be accessible. Also, on Windows, verify that your Windows Firewall is not preventing access on the postgresql port.
  • You may need to configure the pg_hba.conf file (located in PostgreSQL's data directory). This file specifies who has access to the database and where from. After modifying the pg_hba.conf file you will need to refresh postgreSQL using 'pg_ctl reload' .
  • Consult the PostgreSQL website for additional information.
  • For information on administering your PostgreSQL installation, review the server administration section of PostgreSQL's website.
  • For information on tuning your PostgreSQL installation for better performance, review the many tuning recommendations found here.
  • If you are running PostgreSQL 9.1 or later, you will need to set 'standard_conforming_strings = off' in your postgresql.conf.

Get Adobe Flash player

When PostgreSQL is installed you'll be prompted for the credentials of the database superuser.  Here, we'll assume you've called that user postgres.

pgAdminIII is a graphical database management client application. It is widely used and installed with most versions of postgreSQL by default. You can use it to run sql and manage your database(s).

The following actions can be performed either in pgAdminIII (logged in as postgres) or on the command line (these examples assume POSTGRES_HOME\bin is on your PATH).

2.1 Create the XNAT user account

This Postgres account will own and manage the XNAT database.  For purposes of this tutorial we will use xnat01 as the username.

From pgAdminIII: right click on Login Roles–>New Login Role...  Enter xnat01 as the username and then a password.


From the command line (you'll be prompted for the new xnat01 user's password first, then the postgres password):

2.2 Create the XNAT database

 You can use any database name, but for purposes of this tutorial we will use xnat.

From pgAdminIII: right click on Databases–>New Database...  Enter xnat as the database name and select the newly created xnat01 user as the owner.


From the command line (you'll be prompted for the postgres password):

2.3 Create the plpgsql language (8.x and below only):

Note: If you are running Postgres 9.x you can skip this step (plpgsql is installed by default).

plpgsql is a procedural language used by PostgreSQL to create stored procedures and functions. XNAT generates functions which use the plpgsql language and thus requires its installation.  

From pgAdminIII: Select the xnat database and go to File -> Options. Then click on the tab named 'Browser' or 'Display'. Check the 'Languages' checkbox and hit 'OK'. Refresh the left pane.  Then right click on the xnat database-->New Object-->New Language. Enter plpgsql as the 'Name' and the owner of the database as the 'Owner' and hit 'OK'.

From the command line (you'll be prompted for the postgres password):

3. Configure the build.properties file

This file contains information about the location of your Tomcat installation, attributes of the newly generated XNAT installation, details about your database connections, and other important information.  The easiest way is to start from the build.properties.sample file located in the root directory of the XNAT package. Copy this to a new file named build.properties:

The following variables make up the properties file:

  • maven.appserver.home:
    must be set to reference the root directory of your local Tomcat installation (absolute path).  This must be set here, the XNAT build script does not ascertain it from TOMCAT_HOME or CATALINA_HOME.
  • xdat.project.name: 
    This defines the name of your project. It will become the name of your webapp as well.

    Due to limitations in handling of the application name, you should limit the name to letters and numbers. Dashes and at least some other characters are known to cause the web application not to work properly.

  • xdat.project.template: 
    determines the template your new project will use. If the xnat template is specified, then additional screens and classes will be provided for use in your webapp, and the xnat.xsd will be included by default.
    this defines the name of your database.
  • xdat.project.db.driver:
    the Java driver class for the DB connection.  For PostgreSQL this is currently org.postgresql.Driver.
  • xdat.project.db.connection.string:
    defines the connection to your PostgreSQL installation. This connection string should point to the empty database you created in the previous step. You can reference the PostgreSQL documentation for more information on creating a JDBC connection URL..
  • xdat.project.db.user:
    should be the Postgres user account that you created in the previous step. Otherwise, you may run into permission issues that will be difficult to identify.
  • xdat.project.db.password:
    the PostgreSQL password of the user account
  • xdat.archive.location:
    Root directory which contains the image data of all the MRI sessions (required if you wish to use the online image viewer). 
  • xdat.prearchive.location:
    Directory into which the imaging session data will be stored until its archived
  • xdat.cache.location:
    Directory into which the imaging session data will be cached. Also used by the online image viewer to create images.
  • xdat.ftp.location:
    The ftp location is the place where the XNAT FTP Server (available separately) would write files to. This path can be set to a dummy value if you aren't setting up the FTP Server.
  • xdat.build.location:
    This property is currently unused, but is reserved for potential future enhancements to the build process.. This path can be set to a dummy value in the mean time.
  • xdat.pipeline.location:
    Home directory of pipeline scripts
  • xdat.mail.server:
    the address of an accessible SMTP server.  System-generated emails will not work if this doesn't point to a valid mail server, and builds/transfers will appear to fail (only because the last step of the build is to send an email).
  • xdat.mail.port:
    the port on which to connect to said SMTP server

  • xdat.mail.protocol:
    usually smtp

  • xdat.mail.username:
    the username of a valid mail account on xdat.mail.server

  • xdat.mail.password:
    password for said account

  • xdat.mail.admin:
    Email address which should be used for error messages and return addresses of system emails

  • xdat.mail.prefix:
    Beginning of subject line for system-generated emails

  • xdat.url:
    Url that users should use to access your site (included in emails)

  • xdat.enable_new_registrations:
    When new users register, are they allowed to log in right away (true) or must they be approved by an administrator (false)?

  • xdat.modules.location:
    location that the system will monitor for module JAR files

  • xdat.enable_csrf_token:
    Require all HTTP requests to include this token to prevent CSRF attacks (true) or not (false)

  • xdat.security_channel:
    http, https, or any

IMPORTANT: All location variables, including the locations of your Tomcat installation, the archive, prearchive, and cache folders, your pipeline folders, and any other locations, should be given as absolute paths. Also, on Windows systems, backslashes should be replaced with forward slashes, so something like C:\Servers\Tomcat-6.0 would become C:/Servers/Tomcat-6.0.

NOTE: build.properties.sample is pre-populated with many of the values you'll need to build a sample XNAT application. Simply fill in the missing pieces as described above

IMPORTANT: If you want people on other machines to be able to access your instance of XNAT, do NOT leave xdat.url set to localhost. If you leave it set to localhost, some parts of the site will not work properly for users on other machines. Instead it should be set to the URL at which others can access your instance.

UNIX Users: For easier setup, we recommend that the data directories specified above (archive, prearchive, cache, etc.) be owned by the same user account which will execute Tomcat.

4. Run Setup Script

Create an environment variable JAVA_HOME pointing to the location of the installed JDK.  Maven requires this in order to build the project.  Ideally, this should be the same JDK that you will use to run Tomcat.

At the command prompt in the root directory of the XNAT package, run 'bin\setup.bat' (Windows) or 'bin/setup.sh' (UNIX).  This will generate and configure the project which you specified in the build.properties file. It sets up an integrated version of Apache Maven v1.0.2 used to build and deploy XNAT. It creates a .war file (in XNAT_HOME/deployments/PROJECT_NAME/target/) which will be used later to create your web application.

UNIX Users: You may need to allow execution of the .sh scripts in the bin folder (using 'chmod +x bin/*.sh').

IN DEPTH: More info about how the setup scripts work and the artifacts they create.

5. Create Database tables & views

The setup script run in the previous step generated a sql file (xnat.sql) which contains the DDL for your database. It is placed in the deployment directory (XNAT_HOME/deployments/xnat/sql). Run the generated sql in PGAdminIII, or at the command prompt (from XNAT_HOME/deployments/xnat):

The username after the -U flag should match the Postgres user account you created in step 2, and specified in the build.properties file.


  • If you haven’t already installed the language plpgsql, you will get an error on this step. Review step 3.
  • Disregard any warnings like this: 'WARNING: column "rpt" has type "unknown" DETAIL: Proceeding with relation creation anyway.'
  • If you run your sql in PGAdminIII, you will need to remove the first uncommented line '\set ON_ERROR_STOP 1;'. It only works in psql and is unnecessary in PGAdminIII.
  • If it does not recognize the psql command, make sure that POSTGRES_HOME\bin is on your PATH.
  • If you are running PostgreSQL 9.1 or later, you will need to set 'standard_conforming_strings = off' in your postgresql.conf.

6. Modify PATH Environment Variable

ACTION: Create an environment variable called XNAT_HOME with the directory pointing to your XNAT_HOME directory. Use this variable to add the bin directory to your path environment variable (i.e. PATH=$PATH:$XNAT_HOME/bin). On Windows, you will need to modify these environment variables by going to Advanced System Settings. Adding the bin directory to your path will allow you to reference the executables in that directory without specifying the file path to them. This may be problematic if you have multiple XNAT installations, and may be skipped. If you skip this step, then you will need to specify the path to the executables in the following steps. (they are located in the bin directory of your XNAT_HOME).

7. Store initial security settings

At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statement

 This will create an 'admin' user which will be used to insert/view data through XNAT. It also sets some of the default actions and roles for XNAT.

The admin account is your initial account for adding/editing users and setting additional security settings. It has a membership to the ‘Admin’ role which allows it to access the user administration section of the website. The admin user has a default password of ‘admin’ which can be changed through the website.

WARNING: If the PostgreSQL user you used to create your database tables is different than the PostgreSQL user specified in build.properties, you may get a PostgreSQL (permission denied for relation ...) exception when the StoreXML tries to write to the database. Use the 'Grant Wizard' in pgAdminIII to grant the XNAT user permissions for everything in the created db.

Windows Users

If you get a ClassNotFoundException when running StoreXML.bat, it's likely an issue relating to Windows batch files in general. Windows batch files have an 8K length limit for a single command. If you open XNAT_HOME/bin/StoreXML.bat, you'll likely find that the command (which is a single line) is more that 8K characters in length. There are a couple options for fixing this:

  • Move your XNAT_HOME to a directory with a shorter path length.
  • Edit StoreXML.bat, and replace the absolute classpath entries with relative ones. For example, change the first entry (something like C:/my/path/to/xnat/classes) to ../../classes (assuming you are running StoreXML from a working directory of XNAT_HOME/deployments\xnat).

Fortunately, when we move to a single WAR build (in XNAT 1.7 or 2.0), this step will no longer be necessary.

8. Store Example Custom Variable Sets

At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statement:

(The -u admin -p admin states the username and password of the admin account , who is inserting the data.)

This creates additional variable sets which can be used by particular projects in XNAT to customize the options for subject demographics. This step is optional.

WARNING: If you encounter a java.lang.RuntimeException that references tools.jar when calling StoreXML, confirm that Tomcat is pointed at a JDK installation rather than a JRE. In Windows, this may require configuring the Tomcat service settings.

9. Deploy the Webapp

The setup script (step 4) created a WAR file in XNAT_HOME/deployments/PROJECT_NAME/target/. This WAR file can be copied to the webapps directory of your Tomcat server, and will be deployed when the server starts up.

ALTERNATE METHOD: For easier debugging, if your Tomcat server is located on the same file system as your XNAT installation (i.e. is accessible from the XNAT_HOME directory), then you can run the setup and update scripts with the -Ddeploy=true flag:

Linux or OS X

The scripts will build or update your deployment and deploy the web application directly to Tomcat. This prevents the need to continually delete/replace the WAR file for the XNAT application.

10. REST API Configuration

Only Required for 1.6.0

As of 1.6.1, the build script will configure this setting automatically. On newer versions of XNAT you can ignore the rest of this step.

If you’re running your site as the root application (i.e. your URL is http://myserver), then check the file WEB-INF/web.xml in your deployed application. There’s a setting in there called org.restlet.autoWire. That should be set to false.

If you’re running your site as an application within the container (i.e. your URL is http://myserver/xnat or something similar), then your autoWire setting should be set to true (this is the default setting).

If you forget this step, the webapp will start up OK but none of the REST calls will work (you'll see this manifest itself as "ERROR 500" messages on the initial configuration screen).

11. Start the webapp and login

If you're running Tomcat as a service, and it's not already running, start the service.  On Windows you can do this through the system tray icon.  On UNIX, the command will be something like sudo service tomcat6 start.  

If you're running Tomcat as a standalone app, start it using the startup script in your installation’s bin directory (startup.bat for Windows, startup.sh for UNIX).  Windows users: As of Tomcat 6, startup.bat doesn't work out-of-the-box if your working directory is something other than Tomcat home when you start the script.  To remedy this, you can create a CATALINA_HOME environment variable that points to your Tomcat home.  

UNIX Users: You may also want to verify that the Tomcat user owns the directory containing XNAT-specific logs (TOMCAT_HOME/webapps/xnat/logs).

In your Internet browser, proceed to the XNAT webapp (usually http://localhost:8080/PROJECT_NAME).  Login to the site using the username ‘admin’ and the password ‘admin’. This logs you in as the Admin account.

WARNING for Ubuntu users: If you encounter an error message of 'HTTP 404- Requested Resource Is Not Available' when accessing your XNAT site, review the discussion group for details on how to resolve the issue.

12. Complete the Configuration Form

On your first login to the site, you'll be taken to the configuration screen.  Most of the fields will be pre-populated with default values based on what you specified in build.properties (you are free to change them now, of course).  The file system paths should be absolute file paths to any directory on your server (or its networked drives).  These directories will be accessed by Tomcat, so permissions must allow the user who runs Tomcat to create/modify contents of these directories.

One field that you will have to enter here is the Site ID.  It should be a short, one-word name or acronym which describes your site.

13. Create a new user (Optional)

If you specified xdat.enable_new_registrations=true in build.properties, any new user accounts will be auto-enabled.  If false, you will have to log in as as admin and approve the new user before the account is usable.

14. Test the basic XNAT functionality

Create a new project.

Click on Upload Images.  Choose the newly created project.

Upload a DICOM set, preferably one you know works in XNAT or on Central (you can try to break things later).
Two sample DICOM sets are available on the nrg site.

Use the archiving feature to Archive the session (includes creating a subject).

Wait a couple minutes and then refresh the MR Report page. There should be some file counts in the scan summary section. If so, your session was successfully archived. You should receive an email stating this (if SMTP was configured properly). Click Download Images to confirm this.

If you are able to do all of this, then your installation should be up and running. Let us know if you have any problems.   

  • No labels

1 Comment

  1. 7. Store initial security settings

    If Tomcat and/or Apache/Nginx is running you may get a error like:

    Error Storing File.
    (301)Moved Permanently

    Make sure none of them is running!