Step 5 of 8 Download and install XNAT

You've built the basic infrastructure for XNAT, so now you can install the actual application.

There are three steps to getting XNAT installed:

• Download the XNAT application and pipeline engine
• Install the XNAT pipeline engine
• Install XNAT into Tomcat

Download the XNAT application and pipeline engine

If you have the Workshop USB drive, skip this step

You don't need to download the XNAT war file or the Pipeline snapshot zip file, if you have the XNAT Workshop USB drive. Unzip the xnat-workshop-local.zip archive, then find the .war and .zip files in the /local/downloads folder on your USB drive.

Then, copy those two files into the folder on your hard drive that contains your Vagrantfile.

From your Vagrant SSH prompt, you can now see those files by typing ls /vagrant. You should see the following:

CODE

xnat@xnat-11:~$ ls /vagrant
Vagrantfile  xnat-pipeline-1.7.0-SNAPSHOT.zip  xnat-web-1.7.0-SNAPSHOT.war

Then, to make the rest of this tutorial work smoothly, copy those files into your home (~) directory by performing both of the following commands.

CODE

xnat@xnat-11:~$ cp /vagrant/xnat-web-1.7.0-SNAPSHOT.war ~
xnat@xnat-11:~$ cp /vagrant/xnat-pipeline-1.7.0-SNAPSHOT.zip ~

The XNAT application and pipeline engine can be downloaded in different forms–as completed applications, source code, etc.–but currently the easiest way, especially from your command line, is from each application's code repository download section:

xnat@xnat-11:~$ wget https://bitbucket.org/xnatdev/xnat-web/downloads/xnat-web-1.7.0-SNAPSHOT.war
...
2016-05-29 23:00:53 (8.28 MB/s) - ‘xnat-web-1.7.0-SNAPSHOT.war’ saved [158898650/158898650]
 
$ wget https://bitbucket.org/xnatdev/xnat-pipeline/downloads/xnat-pipeline-1.7.0-SNAPSHOT.zip
...
2016-05-29 23:01:19 (6.58 MB/s) - ‘xnat-pipeline-1.7.0-SNAPSHOT.zip’ saved [33947989/33947989]

Install the XNAT pipeline engine

The XNAT pipeline engine provides the ability to execute processing tasks that are resource intensive, long running, or otherwise unsuited for execution within the Tomcat process space. To install the pipeline engine, you'll need to extract the installer from the downloaded zip archive, configure a few properties, then run the installer.

xnat@xnat-11:~$ mkdir pipeline-installer
xnat@xnat-11:~$ cd pipeline-installer
xnat@xnat-11:~/pipeline-installer$ unzip ../xnat-pipeline-1.7.0-SNAPSHOT.zip
xnat@xnat-11:~/pipeline-installer$ ./setup.sh email@myschool.edu smtp.myschool.edu http://xnat-11.xnat.org XNAT /data/xnat/pipeline

At this point, a lot of stuff will happen, but basically the pipeline engine will be installed into the folder specified at the end of the setup.sh command, in this case /data/xnat/pipeline. This is an important thing to remember because you'll need to configure that location in the last step of configuring XNAT.

Problems?

You may get an error message like this when trying to run the pipeline set-up script:

CODE

Exception in thread "main" javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty

If you do see this, you need to become root or sudo and run the following command:

CODE

sudo update-ca-certificates -f

This will clear existing security certificates and update them from the latest configuration. If you continue to have issues, please speak with a member of the XNAT development team.

 

To verify that the pipeline engine installed properly, you can check the contents of the pipeline installation folder. This should look something like this:

xnat@xnat-11:~/pipeline-installer$ ls /data/xnat/pipeline/
ant-tools  bin  catalog  cluster_utils  config  image-tools  lib  log4j.properties  nrg-tools  pipeline.config  pipeline-tools  sample_pipelines  schema  scripts  validation-tools  xnat-tools

Install XNAT into Tomcat

The final step is to install the XNAT application into Tomcat. XNAT 1.7 is distributed as a war, which stands for "web application archive". To deploy a war file into Tomcat, all you need to do is copy the file into the webapps folder of the Tomcat installation, which, in this context, is located at /var/lib/tomcat7/webapps.

There's one catch however. The file you downloaded will be named something like xnat-web-version.war (for the XNAT workshop, this version will be 1.7.0-SNAPSHOT). When you copy a war file into Tomcat's webapps folder, the application is deployed to the server with an application context (which is the top-level path after the server name in the URL, e.g. http://xnat-11.xnat.org/this) set to the name of the file without the war extension. That means that copying xnat-web-1.7.0-SNAPSHOT.war into the webapps folder would mean you'd access your application at the URL http://xnat-11.xnat.org/xnat-web-1.7.0-SNAPSHOT. That's not very handy.

Instead you should copy the file to the name ROOT.war. ROOT has a special meaning for the Tomcat application deployer: an application named ROOT is deployed as the root application, that is to the top-level path ('/'). You should then copy your war file to the webapps folder and name it ROOT.war:

xnat@xnat-11:~/pipeline-installer$ cd ..
xnat@xnat-11:~$ sudo service tomcat7 stop
xnat@xnat-11:~$ rm -rf /var/lib/tomcat7/webapps/ROOT*
xnat@xnat-11:~$ cp xnat-web-1.7.0-SNAPSHOT.war /var/lib/tomcat7/webapps/ROOT.war

Completed!

You've installed the XNAT application into your Tomcat application folder as the root application. Once you complete one more configuration step, you'll access your new XNAT at the URL http://xnat-11.xnat.org. Much better! 

Go to the next step