icon-gettingStarted.png
Getting Started
Prerequisites for installing XNAT
Download XNAT
Step by Step Guide to Installing XNAT

Installing DicomServer


Custom Installation Options

Build From Source

Download XNAT in a Virtual Machine

[Edit Nav]


Step-by-Step Guide to Installing XNAT

These installation instructions guide a user through the installation of a sample XNAT installation. It is recommended that prospective users/developers install the sample XNAT implementation using this tutorial. Please review and install the prerequisites before proceeding with this tutorial.

1. Unzip the distribution into a local directory

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.

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.
  • 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 (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.


2. Create Database

ACTION: If you haven’t already, create an empty database in your PostgreSQL installation. You can use any database name, but 'xnat' is expected for the tutorial and will be used throughout the tutorial. You can create the database using the function ‘createdb DBNAME ’. See the PostgreSQL documentation for more information.

PostgreSQL should be completly installed and tested according to the PostgreSQL documentation before proceeding.

PostgreSQL Tips


  • XNAT has been tested with PostgreSQL version of 7.4 and newer.
  • To guarantee proper installation of postgreSQL, all of the installation steps (http://developer.postgresql.org/pgdocs/postgres/installation.html ) should be performed, including the creation of a test database.
  • PostgreSQL is usually installed using a seperate OS user account (often called 'postgres'). Setting up a database and creating languages are easiest when the user is logged in to this OS account. An additional database user account can be created for use by XNAT using the 'createuser' executable . This user can be given ownership of the database when the database is created by the postgres account using the '--owner' tag. That database user will be tied to XNAT in step 4.
  • 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).

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.


3. Create 'plpgsql' language.

ACTION: If you haven’t already, create the 'plpgsql' language for your postgreSQL database. You can do this using the function ‘createlang plpgsql DBNAME ’. See the PostgreSQL documentation for more information.

SUMMARY: 'plpgsql' is a procedural language used by PostgreSQL to create stored procedures and functions. It is well documented in books and on the internet. XNAT generates functions which use the 'plpgsql' language and thus requires its installation.


4. Configure the build.properties file

SUMMARY: The build.properties file is located in the root directory of the XNAT package. The file contains the location of your Tomcat installation and details about your database connections. The xdat.project.name variable will become the name of the generated project. This will become the name of any generated webapps as well. The xdat.project.template variable specifies whether or not your new project will use a template. To create an XNAT project, this variable must be set to ‘xnat’. Set the db name and connection information to your postgres installation. (This db connection string/name should point to a pre-created empty database of this name). The initial build.properties is set to create an XNAT project called ‘xnat’. You simply need to create an empty database called ‘xnat’ (see step 2) and set the appropriate user name and password. Also, the maven.appserver.home variable must be set to reference the root directory of your local Tomcat installation (abslolute path).

The following variables must be set at this point:
  • maven.appserver.home:equals TOMCAT_HOME
  • xdat.project.db.user:the PostgreSQL user used to create the XNAT database.
  • xdat.project.db.password:the PostgreSQL password used to create the XNAT
  • xdat.archive.location:location where uploaded files will be stored
  • xdat.prearchive.location: location where uploaded files will be temporarily held until they are 'archived'.
  • xdat.cache.location:location where deleted files will be placed.xdat.smtp.server: the address of an accessible SMTP server (required for emails to work)
  • xdat.admin_email:your email address (where error messages will be sent)

NOTE: The distribution is preconfigured to build a sample XNAT application. Simply specify your webapp location, db username, db password, and admin email address and proceed. If you created a database with a name other then 'xnat', you will need to change the xdat.project.db.name and xdat.project.db.connection.string variables accordingly.

IN DEPTH: More info about build.properties


5. Run Setup Script

ACTION: Setup the environment variable JAVA_HOME pointing to the location of jdk.
At the command prompt in the root directory of the XNAT package, run ‘bin\setup.bat’ (WINDOWS) or ‘bin/setup.sh’ (UNIX).

SUMMARY: 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.

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

IN DEPTH: More info about the setup process


6. Create Database tables & views

ACTION: The setup script run in step 5 generated a sql file (xnat.sql) which contains the DDL for your database. It is placed in the your new deployment directory (XNAT_HOME/deployments/xnat/sql). Run the generated sql in PGAdminIII, or at the command prompt:
psql -d DBNAME -f sql/PROJECT_NAME.sql -U USER_NAME
The USER_NAME should match the username you specified in the build.properties file.

SUMMARY: You need to run the generated sql (xnat.sql) in your empty XNAT database before continuing.

WARNINGS:
  • 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.


7. 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). 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. The executables are located in the bin directory of your XNAT_HOME.


8. Store initial security settings

ACTION: At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statement
StoreXML -project PROJECT_NAME -l security/security.xml -allowDataDeletion true
Replace the PROJECT_NAME with the value of the xdat.project.name variable defined in the build.properties. The default PROJECT_NAME is 'xnat'.

SUMMARY: This will create two users (admin & boss) 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.

The boss account is used to authorize changes which are made by ‘Admin’ users. Until user privileges have been authorized by the ‘boss’, the changes will not be in effect. The boss account has a membership to the ‘Bossman’ role which allows it to authenticate users.

WARNING: If the database (PostgreSQL) user you used to create your database tables is different then the database (PostgreSQL) user you assigned to XNAT, 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.

9. Store Example Custom Variable Sets

ACTION: 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.)

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

WARNING: If you encouter a java.lang.RuntimeException while using the StoreXML which references 'tools.jar', confirm that the java version for Tomcat is pointed at the JDK version of java (rather then JRE). In windows, this may require configuring the Tomcat service settings.


10. Deploy the Webapp

ACTION: The setup script (step 5) 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 SETUP: (Instead of using the WAR file) For easier debugging, if your Tomcat server is located on the same file system as your XNAT installation (is accessible from the XNAT_HOME directory), then you can run ‘bin\update.bat -Ddeploy=true ’ (WINDOWS) or ‘bin/update.sh -Ddeploy=true ’ (UNIX). The update script will update your deployment with any modifications which have been made to the PROJECT directory, and then deploy the web application directly to the webserver. This prevents the need to continually delete/replace the webapp WAR file.


11. Start the webapp and login

ACTION: Start your Tomcat server using the startup script in your installation’s bin directory. In your Internet browser, proceed to the XNAT webapp on your local host (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: (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 Default Settings Form

All fields are required. The location variables should be absolute file paths to any directory on your server (or its networked drives). Obviously this will be accessed from with TOMCAT so permissions must allow the user who runs TOMCAT to create/modify contents of these directories.
  • SITE IDshould be a ONE word (or acronym) that describes this installation (like, TEST or DEMO or CENTRAL).
  • SITE URLshould be the URL users will use to access your site. This will be used in emails and redirects. It should contain ports and webapp name if necessary. Default installs can probably use http://localhost:8080/xnat.
  • Site Admin Email Address:Should be your email address
  • SMTP Host (Server):Should be an accessible SMTP SERVER. Emailing will not work if this isn't correct, and builds/transfers will appear to fail (only because the last step of the build is to send an email).
  • The Require Login and Enable new registrations variables govern how new users access the site.
  • The archive location is the directory where XNAT will place all permanently archived data.
  • The prearchive location is the directory where XNAT will temporarily store data until it is archived.
  • The cache location is the place deleted files or temporary files are written to.
  • The build location may be used in future development in the build process. This path can be set to a dummy value in the mean time.
  • 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.
  • The Pipeline Installation Location is the place where you checked out the pipeline cvs module to (i.e. XNAT_HOME/pipeline). (This should be populated automatically).


13. Create a new user (Optional)

Depending on how your default settings, this may require you entering the site as admin and approving the added user before the account is usable.


14. Test the basic XNAT functionality

Create a new project. (use the default directories, include Subjects and MR Sessions).

Click on Upload Images

Upload a DICOM set, preferably one you know works in XNAT 1.4 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 several 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.

Also, from the Project report page, try the Download Images.

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.

15. Install DICOM Server

Follow the detailed instructions
here.