Quick Tutorial
This quick tutorial guides 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.
- Unzip the distribution into a local directory
- Create Database
- Create 'plpgsql' language
- Configure the build.properties file
- Run Setup Script
- Create Database tables & views
- Modify 'path' Environment Variable
- Store initial security settings
- Store sample investigators
- Deploy the Webapp
- Start the webapp and login
- Configure sample security settings
- Authorize your changes
- Insert sample subject data
Please review and install the prerequisites before proceeding with this tutorial.
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.
|
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 here (http://www.postgresql.org/docs/7.4/interactive/app-createdb.html) for more information. |
|
PostgreSQL Tips
|
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 here (http://www.postgresql.org/docs/7.4/interactive/app-createlang.html) 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. |
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 database.
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.project.image.thumbnail.location: location image thumbnails can be stored.
xdat.project.image.lo_res.location: location Lo-Res images will be stored.
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.
More info about build.properties
ACTION: 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').
More info about the setup process
ACTION: The setup script run in step 3 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.'
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.
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.
ACTION: At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statements ‘StoreXML -project PROJECT_NAME -l work/sample-investigator1.xml -u admin -p admin -allowDataDeletion true’ and ‘StoreXML -project PROJECT_NAME -l work/sample-investigator2.xml -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.) Add the '-quiet' attribute to reduce the amount of info written to the console.
SUMMARY: Security in XNAT is based on a subject or experiment’s investigator. For each data type, the admin will decide which investigator’s data a given user can access. Thus, in order to setup security in XNAT, there must be an investigator. Running this step, adds two sample investigators which can then be used for security configuration.
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.
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.
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.
(STEP 12 is only necessary if data types in your archive are ‘secured’. This can be controlled in the data types area of the administration section of the website. By default, data types are secured. To secure/un-secure data types, edit the data types in the administration to be ‘secured’. )
ACTIONS: Click on the ‘Administration’ link. This will list all of the loaded user accounts.
Click on the ‘admin’ link. This brings up the user report for the admin account.
Click on the ‘Change Permissions’ link on the right. This brings up the edit permissions page.
At the bottom of the screen, the current data types will be listed. Click on the plus signs next to the data types. Check the boxes for Create, Read, and Edit for the investigators. (This will give the admin account Create, Read and Edit privileges for data of this type belonging to this investigator). (Additional data types and investigators can be added through the administration section). Click Submit.
SUMMARY: All security changes must be approved by a boss account. So, either click the ‘Submit for Authorization’ link and an email will be sent to the boss account, asking him/her to authorize these changes… or click ‘Print’ and a printable PDF version will be loaded which can be submitted directly to the boss… or click ‘Submit’ and the changes will be saved without further action. For our purposes, click the submit button to save your changes. (The email addresses default to the one supplied in your build.properties file. You can change these through the website.)
ACTION: Logout of the website, and log back in as the boss account (username=boss/password=boss). Proceed to the administration section and click on the admin account again. You will now have the option of authorizing the account’s permissions. Go ahead and click the Authorize link. This will confirm the previous changes.
You can now logout, and log back in as the admin account. You will now have links to MrSession data and Subject data.
ACTION: At the command prompt in your XNAT deployment (XNAT_HOME/deployments/xnat) run the following statement ‘StoreXML -project PROJECT_NAME -l work/sample.xml -u admin -p admin -allowDataDeletion true’.
SUMMARY: This will insert some sample data into XNAT. This information will be visible through the admin account on the website. (Notice: This step must be performed AFTER you configure the security settings. Otherwise the change will not be allowed to proceed.)
BIRN | HHMI | Harvard University | Washington University
