Welcome to the caNanoLab 2.0 Installation Guide.
To Get Support
For any general information about the application, application support, or to report a bug, contact Application Support.
To Print the Guide
You can create a PDF of the guide. For instructions refer to the tip Printing multiple pages. If you want to print a single page, refer to Printing a page.
Topics in this document include:
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:
Important 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:
TechnologiesOpen Source Java Software Development Kit (JDK) version 6.0
{+}http://www.oracle.com/technetwork/java/javase/downloads/jdk6-downloads-+1637591.html
- JBoss version 5.1.0 {+}http://sourceforge.net/projects/jboss/files/JBoss/JBoss-+ 5.1.0.GA/
- Jakarta Ant version 1.7.x {+}http://archive.apache.org/dist/ant/binaries/+
- MySQL version 5.1.x {+}http://dev.mysql.com/downloads/mysql/5.1.html+
NOTE: In release 1.5.4, we have upgraded the technology stack for the web application, but the technology stack for the caNanoLab grid service has not been upgraded due to the requirements of caGrid 1.3. If you'd like to install caNanoLab grid service, please refer to the caNanoLab Release 1.5.3 Installation Guide for the required technology stack for installing the caNanoLab grid service.
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/.+
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
The caNanoLab source codes and build scripts for caNanoLab web application and database are distributed as a zip file named caNanoLab_1.5.4.zip at {+}https://ncisvn.nci.nih.gov/svn/cananolab/dist/caNanoLab_1.5.4.zip+.
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 |
| Action |
| |
1. |
| Extract the caNanoLab_1.5.4.zip to a location on your local system, for |
| |
| 1 | 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>: |
|
|
|
| build |
|
|
|
| cananolab-db |
|
|
|
| cananolab-grid |
|
|
|
| cananolab-webapp |
|
|
|
| common |
|
|
|
|
|
|
Step | Action |
|
|
Step | Action |
| example, US
|
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 |
| Execute the Ant build script build.xml located at |
| If you are NOT using LDAP for user authentication, you can skip this step. If you |
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:
Tables 72
Example: Issue the following query at the MySQL prompt, logging in as root: mysql> select count 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.
This installation guide only discusses the steps for migrating from release 1.5.2 or 1.5.3 in MySQL to release 1.5.4 in MySQL. If you have previously installed caNanoLab in MySQL prior to release 1.5.1, you'd have to migrate to release 1.5.1 first, one release at a time. Please see the install instructions for each release at {+}http://gforge.nci.nih.gov/frs/?group_id=69+ for details.
Follow these steps to complete the required data migration from release 1.5.2 or release 1.5.3 in MySQL to release 1.5.4 in MySQL:
Step | Action |
|
|
Step | Action |
| If you are NOT using LDAP for user authentication, you can skip this step. If you |
| If you are NOT using LDAP for user authentication, you can skip this step. If you
|
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 assumed that the default configuration is used for deploying caNanoLab web archive files. For example, in JBoss 5.1.0, the default configuration is located at the directory
<JBOSS_HOME>/server/default. The caNanoLab web archive file shall be deployed at the directory <JBOSS_HOME>server/default/deploy.
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 |
|
|
|
|
Step | Action |
|
|
| We recommend increasing the JBoss JVM heap size to 1G bytes and permanent generation (permgen) memory space to 256M bytes by updating the file |
|
|
Step | Action |
| <priority value="WARN"/> |
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.
Since release 1.5.2, as a part of the database seed data, two default user groups have been created: Public and Curator. The group Public has been assigned role R (read-only) public protocols, samples and publications. The group Curator has been assigned role CURD (create, update, read and delete) to all protocols, samples and publications in the system. When a user first logs into caNanoLab, he/she will be automatically added to the Public group so he/she can see all public data. The user would need to be added to the Curator group in the UPT tool in order to have Curator access.
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.
Step | Action |
|
|
|
|
|
|
|
|
|
|
1. |
|
Follow similar steps to create other application user accounts as appropriate.
NOTES: Since release 1.5.2, if you are not using LDAP for user authentication, superadmin or caNanoLab administrators maintains the passwords for user accounts. The UPT tool doesn't allow users to manage their own passwords.
Publicly available data can be browsed through Browse caNanoLab links on the home page without logins.
At each new data submission, the user who creates the data and the Curator group are automatically assigned role CURD to the newly created data.
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
Telephone: 301-451-4384
Toll free: 888-478-4423