- About XNAT
- News & Events
- XNAT Marketplace
- Contact Us
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:
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).
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.
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:
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).
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):
createuser -U postgres -S -D -R -P xnat01
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):
createdb -U postgres -O xnat01 xnat
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):
createlang -U postgres -d xnat plpgsql
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:
cp build.properties.sample build.properties
The following variables make up the properties file:
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.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..
the port on which to connect to said SMTP server
the username of a valid mail account on xdat.mail.server
password for said account
Email address which should be used for error messages and return addresses of system emails
Beginning of subject line for system-generated emails
Url that users should use to access your site (included in emails)
When new users register, are they allowed to log in right away (true) or must they be approved by an administrator (false)?
location that the system will monitor for module JAR files
Require all HTTP requests to include this token to prevent CSRF attacks (true) or not (false)
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.
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.
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):
psql -d xnat -f sql/xnat.sql -U xnat01
The username after the -U flag should match the Postgres user account you created in step 2, and specified in the build.properties file.
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).
At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statement
StoreXML -l security/security.xml -allowDataDeletion true
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.
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:
Fortunately, when we move to a single WAR build (in XNAT 1.7 or 2.0), this step will no longer be necessary.
At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statement:
StoreXML -dir ./work/field_groups -u admin -p admin -allowDataDeletion true
(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.
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:
bin/setup.sh -Ddeploy=true bin/update.sh -Ddeploy=true
bin\setup.bat -Ddeploy=true bin\update.bat -Ddeploy=true
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.
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).
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). 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.
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.
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.
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.