hid:WebappQuickstart
From NITRC Wiki
HID Web App Quick Start Guide
Prerequisites
- JDK 1.6+ is necessary for HID web application which uses Java generics is a major Java language enhancement only available Java 5 (JDK 1.5) or later. The latest JDK available is recommended. (http://java.sun.com/j2se/downloads/)
- Apache Ant for build (1.6.x or later) (http://ant.apache.org/)
- Jakarta Tomcat servlet/JSP container (http://jakarta.apache.org/tomcat/)
- Make sure your database is setup for HID web application
Preliminary Database Setup
Make sure your database schema matches your HID web app version
Postgres Support
Postgres is the recommended and supported version starting with HID app version 2.0.3 and later.
Use the latest Postgres db generation scripts available via;
- Using a Subversion client from NITRC HID project site at http://www.nitrc.org/projects/hid.
svn checkout https://www.nitrc.org/svn/hid/schema/tags/release-2.2
Assuming, you have run svn checkout command in your home directory ($HOME), you will have a directory $HOME/release-2.2/schema, which will be called $SCHEMA_HOME in the rest of this document. The instructions are in $SCHEMA_HOME/Postgres/db_objects/README file.
Oracle support
As of HID web app version 2.0.3, Oracle version of HID schema is not maintained.
Checking the database static data integrity
You can check if your database has the necessary minimal static data for HID web app to function via the following ant task
ant db-integrity-check
Before being able to do this you need to build and deploy for web app following instructions in Quick Start section. For Oracle databases, you need to specify the database schema name (BIRNWEB for fBIRN HIDs) when prompted. For Postgres databases just press return. If your database has the correct static data, you will get
[groovy] The necessary static data to ensure correct operation seems to exists in your database!
When the patches are successfully applied or for a new database created using the latest schema generation scripts from https://www.nitrc.org/svn/hid/schema/tags/release-2.2, you should have a HID database (Oracle or Postgres) ready to be used with HID web application.
Quick Start Guide
Getting the source code from stratch
svn checkout https://www.nitrc.org/svn/hid/clinical/tags/release-2.2
Assuming, you have run svn checkout command in your home directory ($HOME), you will have a directory $HOME/release-2.2/clinical, which will be called $CLINICAL_HOME in the rest of this document.
Build and Deployment
Copy $CLINICAL_HOME/build.properties.template to $CLINICAL_HOME/build.properties and edit the Tomcat installation directory information to point to your tomcat installation. In the example below Tomcat version 4.1.24 is installed in directory /data1/opt/tomcat-4.1.24.
# 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
In $CLINICAL_HOME, run for the first time build and deployment
$ ant clean-all $ ant bootstrap $ ant
Check static data integrity
ant db-integrity-check
For subsequent code updates
$ ant clean $ ant
Running Application
Startup your tomcat server
$ ./$TOMCAT_HOME/bin/startup.sh
Point your browser to http://localhost:8080/clinical/
Enabling Web Services
Login to your primary database as the admin user. Click on the App Configuration left menu link and select Web Services tab and enter the primary database id as the DB ID for Web Services parameter value (See $CLINICAL_HOME/README.html for details) and press the Edit button.
Configuration for using GridFTP/Resource Location Service (RLS) as distributed image storage system
Before you will be able to use any Globus Services such as GridFTP or RLS, you need to enable a trust relationship between your HID web server (Tomcat for example) machine and BIRN. This is accomplished by having BIRN certificate authority (CA) certificates and signing policy files in the /etc/grid-security/certificates directory of the server host machine. If you already have a GridFTP server or client setup you can just copy the /etc/grid-security/certificates directory from that machine to your HID web server machine. Otherwise please consult GT components deployment.
Registering your GridFTP server logical names with Remote Location Service (RLS)
This is only necessary if you are using GridFTP for distributed image storage in a multisite study.
First install HID clients using ant
$ant install-hid-client
After that go to $HID_CLIENT_HOME/bin directory and execute rls_tool.sh The example below registers the logical image location pointers in the (default) HID postgres database hidprdp at host localhost on port 5432 as having corresponding physical locations on the GridFTP server at perception.ucsd.edu using myproxy user bozyurt on the default RLS server rls://rls1.nbirn.org:39281. The default database user postgres is used to retrieve the logical names from the database. The script prompts for the passphrase of the myproxy user (here bozyurt) to retrieve a valid certificate as used to authenticate with the RLS server.
rls_tool.sh -c register-db-content -dbpwd pwd -g perception.ucsd.edu -u bozyurt
rls_tool.sh
Usage: RLSTool -c <command> OPTIONS
-c <command> [register-db-content|register-from-filelist]
Common OPTIONS
-g <gridftp-host> The the gridftp hostname for physical locations where the logical names are mapped to
-u <user-name> Your myproxy user name
-r <RLS-server-url> (default: rls://chi-vm-4.isi.edu:39281)
-m <myproxy-server-host> (default: certs.nbirn.org)
OPTIONS for register-db-content command
-dbhost <db-host> the Postgres database server host name (default: localhost)
-schema <schema> the Postgres database schema name (default: hidprdp)
-dbport <port> the Postgres database connection port (default: 5432)
-dbuser <dbuser> the Postgres database user for connection (default: postgres)
-dbpwd <pwd> the Postgres database user's password
OPTIONS for register-from-filelist
-f <logical-file-name-list>
Preparing Your System for Image Downloads via the Web Interface
Before being able to use HID web app image download and preview features, you need to provide file/object type information (metadata). This can be accomplished using the HID DB administration GUI provided with version 2.2 and up. To run this tool, simply type
ant admin-tool
In the GUI select Data Object Registration Tab.
To prepare your database for image viewing support, select Object Type Registration for ImageViewer tab. Step-by-step instruction are available, if you press Help button. In this panel, registration of structural (t1 and t2) DICOM tar files fo a selected experiment in your image storage for image previewing via the HID web application is done.
To prepare your database for image download support, select Object Type Registration for download tab. Step-by-step instruction are available, if you press Help button. You will assign data types to raw data logical names in your HID, using this panel.
