hid:Webapp detailed config

From NITRC Wiki

Contents 1 Configuration 1.1 Build process for version 1.6.1 and higher 1.2 Build and Deploy 1.3 Running web user interface 1.4 Building the Javadoc documentation 1.5 Download Manager Configuration (as of Version 2.0) 1.6 Downloadable data object types setup (Advanced) 1.7 Freesurfer Derived Data Import 1.8 Freesurfer Derived Data Removal 1.9 Setup for HID web services served over HTTPS with self-signed or lesser known SSL certificates 1.10 Clinical Assessment Metadata/Data Import 1.11 All available Ant Tasks for HID web app 2 Securing your Web Server 2.1 Setup for HID web services served over HTTPS with self-signed or lesser known SSL certificates 2.2 Creating a self signed certificate for Apache web server 2.3 HTTPS setup for Tomcat(Necessary to avoid eavesdropping, man in the middle attacks) 2.3.1 SSL Configuration for Tomcat Servlet/JSP Container as as standalone web server 2.3.2 Adding server certificate to truststore (on the client side)

Configuration

Assuming the full path to the directory you have checked out Human Imaging Database (HID) Web Interface and web application framework as $CLINICAL_HOME

Build process for version 1.6.1 and higher

Copy $CLINICAL_HOME/build.properties.template to $CLINICAL_HOME/build.properties and edit using for Tomcat installation directory information

# The directory where your Tomcat application server is installed
tomcat.home=/data1/opt/tomcat-4.1.24
# servlet jar filename
# In Tomcat v 5.x the servlet jar file is for some reason renamed
# from servlet.jar to servlet-api.jar. If you are using Tomcat
# version 5.x use servlet-api.jar or servlet.jar for earlier
# Tomcat versions
servlet.jar.name=servlet.jar

# The web application name for your HID web app installation.
# For most cases the default will work fine.
webapp.name=clinical

Build and Deploy

In $CLINICAL_HOME, run for the first time build and deployment

$ ant clean-all 
$ ant bootstrap
$ ant 

One-time per HID web app release with database schema change bootstrapping, asks for site/user specific information to build a minimal users.xml file to connect to your database and configure your web based user/database/application configuration with sensible default values.

For later updates

$ ant clean 
$ ant

ant clean-all removes everthing deployed under $TOMCAT_HOME/webapps/clinical and also deletes every generated configuration file to start from scratch ant clean removes the compiled java classes, properties files and the struts-config.xml file.

Running web user interface

1. Start Tomcat

$ $TOMCAT_HOME/bin/startup.sh

1. open a browser (Netscape (4.7 and higher/Mozilla 1.0.2 or higher or Internet Explorer 5 and higher ) and type http://localhost:8080/clinical/

1. Stop Tomcat

$ $TOMCAT_HOME/bin/shutdown.sh

Building the Javadoc documentation

Run

$ ant javadoc

After that, point your browser to $CLINICAL_HOME/doc/api/index.html

Download Manager Configuration (as of Version 2.0)

The section below represents Download Manager configuration section of clinical.properties file. In order to be able to use download manager, your HID database tables nc_dataobjecttype, nc_dataobject and for project download management, nc_dataarchive tables must be properly populated.

By default download manager is available when your database tables (nc_dataobjecttype, nc_dataobject and for project download management, nc_dataarchive tables) are properly populated.

Email notification for the download jobs can be setup, if an email server is available, using the application configuration console ( See for details).

The default recognized file object types are ANALYZE and Eprime which are located in locally accessible file system for the deployed HID web app. More file/data object types can be added to the default configuration file $CLINICAL_HOME/conf/clinical-conf.xml BEFORE the first build and deployment. During the bootstrapping where the minimal users.xml file is generated, the HID database is populated with defaults using the $CLINICAL_HOME/conf/clinical-conf.xml file.

Downloadable data object types setup (Advanced)

Before being able to use dowload manager, the types of data objects that will be downloadable needs to be configured. This can be accomplished by

ant data-object-type-config

This custom ant task allows the addition/deletion and listing of dataobject types supported by the application. For most usage scenarios, this needs to be done only once. After this, tomcat server needs to be restarted.

Freesurfer Derived Data Import

The web services client can be installed by running ant

ant install-hid-client

You will be prompted to enter the installation directory. Before the Fresurfer derived data import client is invoked, you need to populate your database with metadata, which is accomplished by running;

ant import-fsa-metadata

After successful derived data metadata setup, you can run the import client fsa_import.sh, which is available under $HID_CLIENT_HOME/bin directory. Your HID web app server needs to be up and running before you attempt running the Freesurfer derived data import client. Also, you need set the DB ID for Web Services field in the Web Services tab of the Application Configuration Module, available on the left hand side menu, if you have logged in as the admin user for the primary site.

Usage: FSAImportClient -u <webUser> -p <webUserPwd> -x <xcedeDir> -a <shortAnalysisName> \
       -s <snapshotID> [-host <HID-web-app-host>] [-port <port-number>] \ 
       [-context <application-context>] [-useSSL]  [-mrml]
For example:

fsa_import.sh -u b -p b -a FreeSurfer -s 0001 \
-x /home/bozyurt/work/fsanalysis/fBIRNPhaseII__0010/Data/001029291693/scanVisit__0010__0002
   /MRI__0001/t1/Analysis/FreeSurfer__0010__0001 \
-host localhost -port 8080

-x xcedeDir
        XCEDE directory contains XCEDE XML files for the Freesurfer (or other) summary
        derived data including provenance information (provenance.xml). Also the actual
        derived data is included as a tarball (.tgz or tar.gz) in this directory.
-host <HID-web-app-host>
        (Default: localhost) e.g. loci.ucsd.edu
-port <port-number>
        (Default: 8080)
-context <application-context>
        (Default: clinical)
-useSSL	
	use this option if the web service provider HID web app is supporting only HTTPS.
-mrml	
	also upload Slicer MRML files included in the data dir to be uploaded.

Freesurfer Derived Data Removal

The removal the corresponding database records for a Fresurfer derived data session expressed in XCEDE can be done vi the custom ant task

ant remove-fsa-from-db

This ant task will ask for xcedeDir (XCEDE directory), which contains XCEDE XML files for the Freesurfer (or other) summary derived data including provenance information (provenance.xml). Basically the required xcede directory used for the import of the derived data in the first place.

Beware of the fact that the corresponding SRB data is *NOT* removed from SRB.

Setup for HID web services served over HTTPS with self-signed or lesser known SSL certificates

If your HID web app is running on a secure web server with a self-signed certificate or a SSL certificate purchased from one of the lesser known discount SSL certificate providers, chances are that your certificate will be not recognized by the Java web service clients. To resolve this

$ ant install-certificate

and provide the hostname for your secure web server (e.g. loci.ucsd.edu ). Make sure that you are running this as ROOT or as a user with enough privileges to write to your default Java Development Kit (JDK) installation truststore.

Clinical Assessment Metadata/Data Import

The web service clients can be installed by running ant

ant install-hid-client

You will be prompted to enter the installation directory. To import new clinical assessments in XCEDE2 format into your HID database, you can run the assessment import client as_import.sh, which is available under $HID_CLIENT_HOME/bin directory. Your HID web app server needs to be up and running before you attempt running the clinical assessment data import client. Also, you need set the DB ID for Web Services field in the Web Services tab of the Application Configuration Module, available on the left hand side menu, if you have logged in as the admin user for the primary site.

Usage: XCEDE2ServiceCLIClient -u <webUser> -p <webUserPwd> \ 
   -x <xcedeAssessmentFile> -i <protocolID> -v <protocolVersion> \ 
    [-host <HID-web-app-host>] [-port <port-number>] \ 
    [-context <context>] [-useSSL]
For example:

import_as.sh -u b -p b -i "Subjects screening protocol" -v 1 \
-x ses.xcede \
-host localhost -port 8080
-i protocolID
        Corresponding Protocol ID from HID nc_protocol table
-v protocolVersion
        Corresponding Protocol Version from HID nc_protocol table
-x xcedeAssessmentFile
        full path to the XCEDE2 assessment file
-host <HID-web-app-host>
        (Default: localhost) e.g. loci.ucsd.edu
-port <port-number>
        (Default: 8080)
-context <application-context>
        (Default: clinical)

All available Ant Tasks for HID web app

You can check all the high-level ant tasks available for HID web app data management by typing;

$ ant -projecthelp

Buildfile: build.xml

Main targets:

 allTests                 Runs idempotent automatic tests as used by continuous integration. 
                          Please create and setup conf/test.properties file before running the unit tests
 bootstrap                does minimal configuration and prepares the database for application
 clean                    deletes the contents of tomcat/webapps/clinical/ and struts_config.xml
 clean-all                cleans up your tomcat webapps/clinical and all the generated configuration files 
                          (struts_config.xml, users.xml and clinical.properties)
 data-object-type-config  Manages data object types (types of the downloadable data) stored in the database
 db-integrity-check       Checks the primary database for static data integrity
 delete-fsa-metadata      removes Freesurfer analysis metadata from the database. Make sure there is 
                          no freesurfer analysis in the database before attempting this!
 import-fsa-metadata      imports Freesurfer analysis metadata into database
 install-certificate      installs SSL certificate for WS server as trusted
 install-hid-client       installs HID Web service clients
 javadoc                  Generate JavaDoc API docs
 remove-fsa-from-db       Given a Freesurfer XCEDE dataset removes it from the database
Default target: compile

Securing your Web Server

Setup for HID web services served over HTTPS with self-signed or lesser known SSL certificates

If your HID web app is running on a secure web server with a self-signed certificate or a SSL certificate purchased from one of the lesser known discount SSL certificate providers, chances are that your certificate will be not recognized by the Java web service clients. To resolve this

$ ant install-certificate

and provide the hostname for your secure web server (e.g. loci.ucsd.edu ). Make sure that you are running this as ROOT or as a user with enough privileges to write to your default Java Development Kit (JDK) installation truststore.

Creating a self signed certificate for Apache web server

1. Generate a private key

   $ openssl genrsa -des3 -out server.key 1024

   Note: If you don't want to enter passphrase every time Apache server starts don't enter a pass phrase in this step.
2. Generate a Certificate Signing Request (CSR)

   $ openssl req -new -key server.key -out server.csr

   Here make sure the Common Name asked is your hostname (e.g. loci.ucsd.edu).
3. Generate a self-signed certificate

   $ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

   Here the generated certificate is valid for a year (365 days).
4. Assuming your Apache has mod_ssl support and installed under /usr/local/apache

    $ cp server.crt /usr/local/apache/conf/ssl.crt
    $ cp server.key /usr/local/apache/conf/ssl.key

   For more information check this link.

HTTPS setup for Tomcat(Necessary to avoid eavesdropping, man in the middle attacks)

SSL Configuration for Tomcat Servlet/JSP Container as as standalone web server

Create a self-signed certificate valid (say ) for 400 days with a password value of "changeit" for both the certificate and the keystore itself. The following command using Sun JDK tool keytool will both create a keystore in $HOME/.keystore file and add a self-signed certificate with alias tomcat to it.

keytool -genkey -alias tomcat -validity 400 -keyalg RSA

Edit your $TOMCAT_HOME/conf/server.xml file for HTTPS support as indicated in SSL Configuration for Tomcat 5.0/6.0.

Important: Also comment out the Connector for port 8080 in your server.xml file so that your tomcat only serves via HTTPS protocol. After that start your tomcat and point your browser to https://localhost:8443/ for test.

Adding server certificate to truststore (on the client side)

Prepare a truststore for secure remote clients (web services clients)

1. export the RSA certificate with alias tomcat from the keystore of the server machine

          keytool -export -alias tomcat -file tomcat.cer
   

2. import the RSA certificate into your security client's truststore. Every security client needs to access to a local truststore containing trusted server's certificate. The truststore is only needed if you self sign your certificate. The default truststore for your Java installation where the client program will run is named cacerts and usually located under $JAVA_HOME/jre/lib/security/cacerts You need to add the exported certificate tomcat.cer into the default truststore for encrypted access to Apache Axis web service engine running inside the deployed HID web app.

         keytool -import -alias tomcat -keystore $JAVA_HOME/jre/lib/security/cacerts -file tomcat.cer
   

   When asked `Trust this certificate?`, enter Yes. You may need temporarily give write permissions to the truststore file.