NIH | National Cancer Institute | NCI Wiki  

Error rendering macro 'rw-search'

null

Versions Compared

Old Version 12

changes.mady.by.user Jackel, Laura (NIH/NCI) [C]

Saved on

compared with

New Version 13

changes.mady.by.user Jackel, Laura (NIH/NCI) [C]

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Page info
title
title

Welcome to the caNanoLab 2.0 Installation Guide.

...

Table of Contents
minLevel2

Introduction to caNanoLab

Welcome to the cancer Nanotechnology Laboratory (caNanoLab) 1.5.4 Installation Guide. caNanoLab is a data sharing portal designed to facilitate information sharing in the biomedical nanotechnology research community to expedite and validate the use of nanotechnology in biomedicine. caNanoLab allows researchers to share information on nanomaterials including the composition of the nanomaterial, the functions (e.g. therapeutic, targeting, diagnostic imaging) of the particle, the characterizations of the nanomaterial from physico-chemical (e.g. size, molecular weight, surface) and in vitro (e.g. cytotoxicity, blood contact) assays, and the protocols of these characterization.

As of release 1.1, the caNanoLab domain model has been caGrid enabled. In other words, a caNanoLab grid data service can be deployed and registered with caGrid production index server, allowing sharing of public nanomaterial information across the caGrid. In release 1.5, the caNanoLab grid service has been updated to use caGrid 1.3. For more information, see  https://cabig.nci.nih.gov/workspaces/Architecture/caGrid.

Targeted Developer

The caNanoLab application development is best suited for an experienced Java developer who has some familiarity with the following J2EE and related technologies:

Info
titleImportant Background Knowledge

Unix/Linux environment, Windows XP environment or Mac OS environment (Configuring environment variables; Installing Ant, JDK, Apache Tomcat and JBoss servers)

  • Ant build scripts
  • J2EEwebapplicationdevelopmentusingtheStrutsframework,Servlet/JSP's,JavaScript
  • J2EEmiddle-waretechnologiessuchasn-tierservice-orientedarchitectureandsoftwaredesignpatterns
  • HibernateJavapersistenceframwork
  • caGrid1.3infrastructure(forunderstandinghowacaNanoLabgriddataservicefunctions)

General System Requirements

The following open source technologies power a caNanoLab release 1.5.4 web application:

Open Source Technologies

...

The caNanoLab web application has been tested within NCICBIIT against JBoss servers (version 5.1.0) hosted on Windows XP and RedHat Linux systems, and against MySQL 5.1.x databases hosted on RedHat Linux systems and Windows XP systems. Prior to release 1.2.1, the caNanoLab web application had been tested against Oracle 9i databases hosted on Sun Solaris systems, and Oracle 10g XE database hosted on Windows XP.
Download each of the tools listed in the bulleted list above and follow the installation instructions provided with each respective product for your environment. Assistance from a MySQL database administrator is expected to properly configure the MySQL database. For MySQL database configuration and maintenance, it is also helpful to download the MySQL workbench (suite of GUI tools) at  http://www.mysql.com/downloads/workbench/ Exit Disclaimer logo

Grid Service

Setting up a caNanoLab grid service is optional. It is recommended that you install the grid service only after you successfully install the web application and become familiar with submitting and searching data through the web application.

Grid Service Downloads

Since release 1.5.2, there are no separate technology downloads required for installing the caNanoLab grid service, and most can obtained automatically during building of the grid service through Ant.

Obtaining the caNanoLab Source

Source Code

Downloads for caNanoLab are available at caNanoLab GitHub Repository Exit Disclaimer logo. The caNanoLab Software License applies.

Ant Build Properties

Assumptions and Requirements

The caNanoLab source distribution caNanoLab_1.5.4.zip has been downloaded. Ant has been installed. In caNanoLab release 1.5.4, the Ant build script automatically installs the web application, the database and the grid service.

Setting Properties

Follow these steps to set the build and deploy properties required for building and deploying the caNanoLab system.

Step 1.  Extract caNanoLab

Extract the caNanoLab_1.5.4.zip to a location on your local system, for example, C:\caNanoLab_1.5.4. This location is referred as <CANANOLAB_SOURCE> throughout the document. Verify that the following five folders exist in the directory <CANANOLAB_SOURCE>:

...

cananolab-grid

cananolab-webapp

common

Step 2. Edit Ant Properties

Edit the Ant properties file build.properties at
<CANANOLAB_SOURCE>/build by specifying values for the following properties:

  1. file.repository.dir: a directory on the system that hosts the JBoss application server for storing uploaded files, for example,

    C:/apps/caNanoLab
    Note: This directory should be writable by the user that starts the JBoss
    server, and this directory should be created prior to starting the application. Either double back slashes
    or a single forward slash / should be used as the file separator if working on Windows platform.
  2. admin.email: the email address that receives requests for new user accounts, for example, NCICBIIT application support email for the NCICBIIT installation
  3. ldap.authentication.enabled: a Boolean flag for whether or not using LDAP for user authentication in caNanoLab, for example, true

    Note: Please note that default value is true. If you are not using LDAP for user
    authentication, please set this value to false and leave properties 4) through 9) blank.
  4. ldap.host.url: the URL of the LDAP server used for user authentication
  5. ldap.searchable.base: the location in the directory from which the LDAP search begins
  6. ldap.userId.label: the uid label for LDAP, for example, cn
  7. superadmin.login.name: the LDAP login name for the user account who is the super admin of the UPT tool. See page 14 for details on setting up UPT
  8. superadmin.first.name: the LDAP first name for the user account who is the super admin of the UPT tool
  9. superadmin.last.name: the LDAP last name for the user account who is the super admin of the UPT tool
  10. database.server: the name of the server hosting the database, for example, localhost
  11. database.port: the database port number, for example, 3306
  12. database.user: the database user name used in the caNanoLab application, for example, cananolab_app
  13. database.password: the password for the database user specified above,

    for example, go!234
  14. database.system.user: the system database user name that has privileges to create a database, create tables, grant user accesses to a database, for example, root
  15. database.system.password: the password for the system database user

    specified above, for example, rootpass
  16. jboss.server.dir: the JBoss server directory, for example,

    C:/apps/jboss-5.1.0.GA/server/default


    Note: The following properties 17) through 34) are only required if you setting up a grid service. These properties contain metadata about the grid service that are required for the grid index server to visually map the location of a grid service in the caGrid portal, and are useful during grid service auto-discovery. If you are not setting up a caNanoLab grid service, you may leave these properties blank.
  17. application.base.path.linux: a directory on the Linux system that stores the downloaded external software, such as the Globus WS Core binary files, for example, ${user.home}/apps

    Note: This property is currently optional for building the web application and
    the database, and is only required for building the grid service on a Linux system.
  18. application.base.path.windows: a directory on the Windows system that stores the downloaded external software, such as the Globus WS Core binary files, for example, C:/apps
  19. grid.indexserver: the grid index server from which the caNanoLab grid data services can be automatically discovered, for example, http://cagrid- index.nci.nih.gov:8080/wsrf/services/DefaultIndexService, NCICBIIT's production caGrid index server
  20. grid.service.hostname: virtual host name for the JBoss server hosting the grid service, for example, cananolab.nci.gov
  21. grid.service.port: port number configured for the JBoss server hosting the caNanoLab grid service, for example, 80
  22. grid.service.protocol: protocol configured for the JBoss server hosting the caNanoLab grid service, for example, http
  23. application.owner: owner of the caNanoLab grid service, for example,

    NCICBIIT
  24. country: the country in which the caNanoLab grid service is running, for

    example, US

    1. city: the city at which the caNanoLab grid service is running, for example,

      Rockville
    2. zipcode: the zip code at which the caNanoLab grid service is running, for example, 20852
    3. state: the state at which the caNanoLab grid service is running, for

      example, MD
    4. street1: the first part of the street at which the caNanoLab grid service is running, for example, 2115 East Jefferson Street
    5. street2: the second part of the street at which the caNanoLab grid service is running
    6. affiliation: the affiliation of the person who is responsible for maintaining the caNanoLab grid service, for example, NCICBIIT.
    7. email: the email of the person who is responsible for maintaining the caNanoLab grid service, for example, NCICBIIT@pop.nih.gov
    8. phone: the phone number of the person who is responsible for maintaining the caNanoLab grid service
    9. first.name: the first name of the person who is responsible for maintaining the caNanoLab grid service
    10. last.name: the last name of the person who is responsible for maintaining the caNanoLab grid service.

Database Technology

Assumptions and Requirements

The Ant build properties have been set as described on pages 3 through 5. A MySQL database has been set up on a system (local or remote) with a system (or root) account. The system account should match properties 9) and properties 10) in the step 2 of the previous section.

For a Previous Installation

If you have installed caNanoLab prior to release 1.5.4 against an MySQL database, or release 1.2 or release 1.1.1 or release 1.1 against an Oracle database, and have associated production data in these schemas and you would like to continue to use the same data for caNanoLab release 1.5.4 in MySQL, review the following database initialization steps, then go directly to Data Migration on page 7.
If you have a previously installed caNanoLab application running on a JBoss server, stop the server before running the database scripts.

For a New Installation

If you are installing the caNanoLab application for the first time or want to install a new schema for release 1.5.4, follow the steps below to set up the required MySQL schema objects and the seed data for release 1.5.4.

Initializing the MySQL Database

Follow these steps to initialize your MySQL database system:

Step

Action

1

Execute the Ant build script build.xml located at
<CANANOLAB_SOURCE>/build with the target install:new:cananolab-db.

Example: Issue the following commands to execute the Ant script:

C:\>cd C:\caNanoLab_1.5.4\build C:\caNanoLab_1.5.4\build>ant install:new:cananolab-db

Successful execution of the Ant script creates the database schema and seed data required the caNanoLab 1.5.4 release.

2

If you are NOT using LDAP for user authentication, you can skip this step. If you
are using LDAP for authentication, execute the Ant build script build.xml located at <CANANOLAB_SOURCE>/build with the target update:cananolab-db:ldap:upt:superadmin

Example: Issue the following commands to execute the Ant script:

C:\>cd C:\caNanoLab_1.5.4\build C:\caNanoLab_1.5.3\build>ant update:cananolab-db:ldap:upt:superadmin

Successful execution of the Ant script updates the default UPT super admin with the user name entered in the build properties file on page 4.

 

Verification

Once the MySQL database has been created, either through new setup or through data migration (described in the next section), verify that the following numbers of database objects are created:

...

Example: Issue the following query at the MySQL prompt, logging in as root: mysql> select count(star) from information_schema.tables where
table_schema='canano' and table_type='BASE TABLE';

Data Migration

NOTE:
If you are installing caNanoLab 1.5.4 for the first time or installing a new caNanoLab release 1.5.4 schema, you can skip this section.

...

After data migration, refer to the Verification section to verify that the migration has been successful.

caNanoLab Web Application

Assumptions and Requirements

Ant has been installed. Ant build properties have been set up, as described on pages 3 through 5. The database has been installed and verified, as described on pages 6 through 9. The JBoss application server has been installed on a system (local or remote) and can be started at a designated port. JBoss install directory is referred as <JBOSS_HOME> in the document. The JBoss application server host URL is referred as
<APP_SERVER_URL>, for example, cananolab-dev.nci.nih.gov:19080.

...

It is possible to configure Apache server to interface with the JBoss server and set up a virtual host for the caNanoLab application, if you need assistance, please contact NCICBIIT Application Support (info provided at the end).

Installation and Deployment

Follow these steps to install and deploy caNanoLab:

Step

Action

1

Set up an environment variable JBOSS_HOME to point to the JBoss installation directory.

Note: Either double back slashes
or a single forward slash / should be used as the file separator if working on Windows platform, for example, JBOSS_HOME=C:/jboss-5.1.0.GA (C:\jboss-5.1.0.GA would fail).

2

Execute the Ant build script build.xml located at
<CANANOLAB_SOURCE>/build with the target deploy:cananolab-webpp.

Example: Issue the following commands to execute the Ant script:

C:\>cd C:\caNanoLab_1.5.4\build C:\caNanoLab_1.5.4\build>ant deploy:cananolab-webapp

Successful execution of the Ant script generates the following artifacts that include two deployable web archive war files, configuration files and libraries for running the web application in the JBoss environment, and also places these artifacts in the appropriate directories under <JBOSS_HOME>:

<CANANOLAB_SOURCE>/target/dist/exploded/cananolab- webapp/caNanoLab.war

<CANANOLAB_SOURCE>/target/dist/exploded/common/Applica tionSecurityConfig.xml

<CANANOLAB_SOURCE>/target/dist/exploded/common/csmupt. csm.new.hibernate.cfg.xml

<CANANOLAB_SOURCE>/target/dist/exploded/common/csmupt4 23.csm.new.hibernate.cfg.xml

<CANANOLAB_SOURCE>/target/dist/exploded/common/login- config.xml

<CANANOLAB_SOURCE>/target/dist/exploaded/common/mysql- connector-java-5.0.7.jar

<CANANOLAB_SOURCE>/target/dist/exploded/common/upt- ds.xml

<CANANOLAB_SOURCE>/target/dist/exploded/common/propert ies-service.xml

<CANANOLAB_SOURCE>/target/dist/exploded/common/upt- ds.xml

<CANANOLAB_SOURCE>/target/dist/exploded/common/uptEAR. ear

3

We recommend increasing the JBoss JVM heap size to 1G bytes and permanent generation (permgen) memory space to 256M bytes by updating the file
<JBOSS_HOME>/bin/run.conf with the following JAVA_OPTS:

JAVA_OPTS="-Xms512m -Xmx1024m -XX:PermSize=128m - XX:MaxPermSize=256m
-Dsun.rmi.dgc.client.gcInterval=3600000 - Dsun.rmi.dgc.server.gcInterval=3600000"

This configuration file is read when JBoss server starts.

4

When deploying the caNanolab application and the grid service in a production environment, we also recommend updating the default logging behavior of the JBoss server by turning off the unnecessary loggings thus reducing file system requirements for server log files.

Please locate the file <JBOSS_HOME>/server/default/conf/log4j.xml
and add to the beginning of the section Limit categories the following text:
<!-- ================ -->
<!-- Limit categories -->
<!-- ================ -->

<!-- edited for caNanoLab -->
<category name="org.hibernate">

<priority value="WARN"/>
</category>
<category name="org.springframework">
<priority value="WARN"/>
</category>
<category name="org.globus">
<priority value="WARN"/>
</category>
<category name="gov.nih.nci">
<priority value="ERROR"/>
</category>
<category name="org.displaytag">
<priority value="ERROR"/>
</category>
<category name="org.directwebremoting">
<priority value="ERROR"/>
</category>
<category name="net.sf.ehcache">
<priority value="INFO"/>
</category>
<category name="com.mchange.v2">
<priority value="INFO"/>
</category>
<category name="org.jboss">
<priority value="INFO"/>
</category>
<category name="CSM">
<priority value="ERROR"/>
</category>
<category name="Authorization">
<priority value="ERROR"/>
</category>
<!—end of edit for caNanoLab -->

Verification

Once the deployment artifacts have been deployed and the JBoss application server is correctly configured, you can now start the JBoss application server, which in turn starts the caNanoLab application.
Open the URL http://<APP_SERVER_URL>/caNanoLab/ (for example,
http://localhost:8080/caNanoLab). You should see a Welcome/Login page.

User Provisioning Tool (UPT)

Creating User Accounts

Before a user can log in to the caNanoLab application to submit and search data, you must first create his/her user account through the UPT web interface. The caNanoLab application makes use of the NCICBIIT's User Provisioning Tool (UPT), a separate web application, for user account management. The concepts of users, groups, roles, protection groups are defined according the CSM/UPT principles. See the CSM documentation at {+}http://gforge.nci.nih.gov/frs/?group_id=12+ for details on these concepts and the use of the UPT tool.

...

NOTE: Since release 1.5.2, a user must be assigned as a caNanoLab administrator to see the ADMINISTRATION menu item in the application to log into the UPT tool or do update site preferences such as site logo. A user must be assigned as a caNanoLab administrator and assigned to the Curator group to be able to execute the transfer ownership function.

UPT Example

The following steps illustrate an example use of the UPT tool to create a new user, to assign the user to be a caNanoLab administrator, and to assign the user to the Curator group.

...

For more information about how to use the UPT tool for managing user accounts, contact NCICBIIT Application Support at NCICBIIT@pop.nci.nih.gov and request that the caNanoLab technical team give you a demonstration of the UPT tool in the context of the caNanoLab application.

caNanoLab Grid Data Service

Assumptions and Requirements

As noted earlier, please refer to caNanoLab Release 1.5.3 Installation Guide for the technology stack requirements and how to install the caNanoLab grid service.

Contacting Application Support

NCICBIIT Application Support

{+}http://NCICBIIT.nci.nih.gov/NCICBIIT/support+ NCICBIIT@pop.nci.nih.gov

...