NIH | National Cancer Institute | NCI Wiki  

Welcome to the caNanoLab 2.1 Installation Guide.

To Get Support

For any general information about the application, support, or to report a bug, contact caNanoLab-Support@ISB-CGC.org.


To Print the Guide
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 (https://cananolab.cancer.gov). caNanoLab is a data sharing portal that supports the international biomedical nanotechnology research community to expedite and validate the use of nanotechnology in biomedicine. caNanoLab provides support to annotate nanomaterials with characterizations resulting from physico-chemical, in vitro, and in vivo assays and share characterizations and associated nanotechnology protocols in a secure environment.

For more information about the 2.1 updates, refer to the caNanoLab 2.1 Release Note.

Targeted Developer

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

General System Requirements

What is caNanoLab Tested Against?

The caNanoLab web application has been tested within NCI CBIIT against Wildfly servers (version 8.2.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.

Open Source Technologies

Download each of the following tools 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

Obtaining the caNanoLab 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_2.1.zip is downloaded, and Ant is installed.

Note

In caNanoLab release 2.1, the Ant build script automatically installs the web application.

Setting Properties

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

Step 1. Extract caNanoLab

Extract the caNanoLab_2.1.zip to a location on your local system, for example, C:\caNanoLab_2.1. 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 2. Edit Ant Properties

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

PropertyDescription
file.repository.dir

A directory on the system that hosts the Wildfly application server for storing uploaded files, for example, C:/apps/caNanoLab.

Note

 This directory should be writable by the user that starts the Wildfly server, and this directory should be created prior to starting the application. Use either double-back slashes or a single forward slash / as the file separator if working on Windows platform.

admin.email

The email address that receives requests for new user accounts, for example, the NCICBIIT application support email for the NCICBIIT installation.

ldap.authentication.enabled

A Boolean flag to indicate whether or not to use LDAP for user authentication in caNanoLab, for example, true.

Note

The default value is true. If you are not using LDAP for user authentication, set this value to false and leave properties 4) through 9) blank.


ldap.host.url

The URL of the LDAP server used for user authentication.

ldap.searchable.base

The location in the directory from which the LDAP search begins.

ldap.userId.label

The buid label for LDAP, for example, cn.

superadmin.login.name

The LDAP login name for the user account who is the super admin of the UPT tool. Refer to User Provisioning Tool (UPT) for details on setting up UPT.

superadmin.first.name

The LDAP first name for the user account who is the super admin of the UPT tool.

superadmin.last.name

The LDAP last name for the user account who is the super admin of the UPT tool.

database.server

The name of the server hosting the database, for example, localhost.

database.port

The database port number, for example, 3306.

database.user

The database user name used in the caNanoLab application, for example, cananolab_app.

database.password

The password for the database user specified above, for example, go!234.

database.system.user

The system database user name with privileges to create a database, create tables, grant user accesses to a database, for example, root.

database.system.password

The password for the system database user specified above, for example, rootpass.

jboss.server.dir

The Wildfly server directory, for example, C:/apps/wildfly-8.2.0.Final/standalone.

Database Technology

Assumptions and Requirements

For a Previous Installation

If you:

  1. Installed caNanoLab prior to release 2.1 against an MySQL database
    OR
    Installed release 1.2, release 1.1.1, or release 1.1 against an Oracle database,

  2. AND have associated production data in these schemas
    AND would like to continue to use the same data for caNanoLab release 2.1 in MySQL,

  3. Review the following database initialization steps, and then go directly to section, Data Migration.

Wildfly Server

If you have a previously installed caNanoLab running on a Wildfly 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 2.1, follow the steps below to set up the required MySQL schema objects and the seed data for release 2.1.

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_2.1\build C:\caNanoLab_2.1\build>ant install:new:cananolab-db

Successful execution of the Ant script creates the database schema and seed data required the caNanoLab 2.1 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_2.1\build C:\caNanoLab_2.1\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.

Verification

Once the MySQL database is created, either through a 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 2.1 for the first time or installing a new caNanoLab release 2.1 schema, you can skip this section.

This installation guide only discusses the steps for migrating from release 1.5.3, 1.5.4, or 1.5.5. in MySQL to release 2.1 in MySQL. If you have previously installed caNanoLab in MySQL prior to release 1.5.1, you need to migrate to release 1.5.1 first, one release at a time. The 1.5.5 installation guide is available at caNano Lab Release Notes, but previous installation guides are available at the caNanoLab Archive page.

Follow these steps to complete the required data migration from release 1.5.3, 1.5.4, or 1.5.5. in MySQL to release 2.1 in MySQL.

Step

Action

1

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

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

C:\>cd C:\caNanoLab_2.1\build C:\caNanoLab_2.1\build>ant update:cananolab-db

Successful execution of the Ant script updates the database schema and seed data required the caNanoLab 2.1 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_2.1\build C:\caNanoLab_2.1\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.

3

If you are NOT using LDAP for user authentication, you can skip this step. If you are using LDAP for authentication, and you already have user accounts in the system and you have data created by these users whose login names are not their LDAP login IDs, you need to perform the following update:

  1. Update the login_name column of the csm_user table with the LDAP login name for each user in the table: 
    Example:     Issue the following query at the MySQL prompt for each user, logging in as root:
    mysql> update csm_user set login_name='' where login_name='';
    ...Where the token is replaced by the real LDAP login name that corresponds to the old login name. Replace the token with the old login name.

  2. Update the created_by column of tables containing the column with the LDAP login name:
    Example:     Issue the following query at the MySQL prompt for each table containing the created_by column, logging in as root:
    mysql> update sample set created_by='' where created_by ='';
    ...Where the token is replaced by the real LDAP login name that corresponds to the old login name. Replace the token with old login name.

    Note

    If the created_by field contains the word "COPY" in it, update it with a prefix : (colon), where the token is replaced by the real LDAP login name that corresponds to the old login name who created the data. If you do not know the original login who created the data, use the LDAP login of a curator. If you need assistance on completing the data updates for this step, contact the caNanoLab technical team.

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

caNanoLab Web Application

Assumptions and Requirements

  • Ant is installed, and the Ant build properties are set up.
  • The database is installed and verified.
  • The Wildfly application server is installed on a system (local or remote) and can be started at a designated port. Wildfly install directory is referred to as <JBOSS_HOME> in the document. The Wildfly application server host URL is referred as <APP_SERVER_URL>, for example, cananolab-dev.nci.nih.gov:19080 .
  • The default configuration is used for deploying caNanoLab web archive files.
    For example, in wildfly-8.2.0.Final, the default configuration is located at the directory <JBOSS_HOME>/standalone. The caNanoLab web archive file will be deployed at the directory <JBOSS_HOME>standalone/deployments.
  • It is possible to configure Apache server to interface with the Wildfly server and set up a virtual host for the caNanoLab application. If you need assistance, contact caNanoLab-Support@ISB-CGC.org.

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 Wildfly installation directory.

Note

Use either double back slashes // or a single forward slash / as the file separator if working on Windows platform, for example, JBOSS_HOME=C:/wildfly-8.2.0.Final (C:\wildfly-8.2.0.Final 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_2.1\build C:\caNanoLab_2.1\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 Wildfly environment, and also places these artifacts in the appropriate directories under <JBOSS_HOME>:

Artifacts
 <CANANOLAB_SOURCE>/target/dist/exploded/cananolab- webapp/caNanoLab.war 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/ApplicationSecurityConfig.xml 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/csmupt.csm.new.hibernate.cfg.xml 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/csmupt423.csm.new.hibernate.cfg.xml 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/login-config.xml 
 <CANANOLAB_SOURCE>/target/dist/exploaded/common/mysql-connector-java-5.1.26.jar 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/upt-ds.xml 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/properties-service.xml 
 <CANANOLAB_SOURCE>/target/dist/exploded/common/upt-ds.xml
 <CANANOLAB_SOURCE>/target/dist/exploded/common/uptEAR.ear
 <CANANOLAB_SOURCE>/target/dist/exploded/common/bcprov-jdk15on-1.47.jar
 <CANANOLAB_SOURCE>/target/dist/exploded/common/caNanoLab_modules.cli
 <CANANOLAB_SOURCE>/target/dist/exploded/common/caNanoLab_setup.cli
 <CANANOLAB_SOURCE>/target/dist/exploded/common/caNanoLab_deploy.cli
 <CANANOLAB_SOURCE>/target/dist/exploded/common/csmapi-5.2.jar

3

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

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

This configuration file is read when Wildfly server starts.

4

  1. Create a new directory structure C:/local/content/caNanoLab/artifacts and move the following artifacts.
    • csmapi-5.2.jar
    • caNanoLab.war
    • uptEAR.ear
    • bcprov-jdk15on-1.47.jar
    • mysql-connector-java-5.1.26.jar
    • caNanoLab_modules.cli
    • caNanoLab_setup.cli
    • caNanoLab_deploy.cli
  2. Create a new directory structure C:/local/content/caNanoLab/config and move the following artifacts.
    • ApplicationSecurityConfig.xml
    • csmupt.csm.new.hibernate.cfg.xml
    • wikihelp.properties
5.

Start JBoss application server in Standalone mode.

This script assumes the CLI port is running at 19990. If it is different, you need to update port number at the second line in the script.

  1. Type the following:
    • For Windows environment: jboss-cli.bat --file=C:/local/content/caNanoLab/artifacts/caNanoLab_modules.cli and press <ENTER>.
    • For Linux environment: jboss-cli.sh --file=C:/local/content/caNanoLab/artifacts/caNanoLab_modules.cli and press <ENTER>.

  2. Run the remaining caNanoLab_setup.cli and caNanoLab_deploy.cli that deploys the caNanoLab and csmUPT.
    After successful completion, the following output appears in the window.

    Output
     {"outcome"=> "success"}
 {"outcome"=> "success"}
 {"outcome"=> "success"}
 {"outcome"=> "success"}
 {
 "outcome"=> "success",
 "result"=> undefined
 }

  3. Press any key to continue.

Verification

Once the deployment artifacts are deployed and the Wildfly application server is correctly configured, you can start the Wildfly application server, which in turn starts the caNanoLab application.
Open the URL http://<APP_SERVER_URL>/caNanoLab/, for example, http://localhost:8080/caNanoLab . The Welcome/Login page appears.

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 a user account through the UPT web interface. The caNanoLab application makes use of the NCI CBIIT'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. Refer to the CSM documentation for details on these concepts and the use of the UPT tool.

There are three default user groups:

  • Group Public is assigned role R (read-only) public protocols, samples and publications.
  • Group Researcher is assigned Role R (read-only) for all protocols, samples, and publications in the system.
  • Group Curator is assigned role CURD (create, update, read and delete) to all protocols, samples and publications in the system.

When a user first logs into caNanoLab, the user is automatically added to the Public group and can view all public data. The user needs to be added to the Researcher or Curator group in order to have access.

Note

Since release 1.5.2, a user must be assigned as a caNanoLab administrator to see the Administration menu in the application to log into the UPT tool or update site preferences, such as the 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, assign the user to be a caNanoLab administrator, and assign the user to the Curator group.

Step

Action

1

  1. Launch the UPT tool at http://<APP_SERVER_URL>/upt52/Home.action and login as the super admin. If you are NOT using LDAP for user authentication, the default user account/password for super admin is superadmin/superadmin.

  2. Enter csmupt as the application name when prompted at the UPT log in. If you are using LDAP for user authentication, use the LDAP login name and password of the user assigned as the super admin as specified in the Ant build properties file.

    Note

    The user superadmin with the password superadmin was created as a part of the database setup. Only a superadmin user can assign users to be caNanoLab administrators.

2

If you are using LDAP for user authentication, skip this step. If you are not using LDAP for authentication, follow this step to reset the password for superadmin:

  1. Select User > Select an Existing User.
  2. Click on Search and select superadmin, and click on View Details.
  3. Update the User Password field and Confirm Password field.
  4. Click on Update to commit the change.

3

Log in as the super admin, and follow these steps to create a new user and assign the user to be a caNanoLab administrator:

  1. Select User > Create a New User.
  2. Create a new user account named admin with an initial password.
  3. Select Application > Select an Existing Application, and click Search. Select caNanoLab from the application list.
  4. Click View Details, then Associated Admins.
  5. Assign this user to be an administrator for the caNanoLab application.

  6. Click Update Association to commit the change.

    Note

    If you are using LDAP for user authentication, any user login names created in the UPT tool must be a valid LDAP log in name.

4

Before the newly-created user can log into the UPT application, logged in as the super admin, follow these steps to update the required database connection information for the csmupt and caNanoLab applications under the Application tab:

  1. Select Application > Select an Existing Application, and click Search. Select csmupt from the application list.
  2. Click View Details, then update the following fields:
    • Application Database URL, for example, jdbc://mysql://localhost:3306/canano
    • Application Database User Name, for example, cananolab_app
    • Application Database Password, for example, go!234
    • Application Database Confirm Password, for example, go!234
    • Application Database Dialect, for example, org.hibernate.dialect.MySQLDialect

    • Application Database Driver, for example, com.mysql.jdbc.Driver

      Note

      Refer to Edit Ant Properties for the appropriate values for these fields. Values for Application Database Dialect and Application Database Driver must be exactly entered as shown above.

  3. Repeat the steps to update the database connection information for the caNanoLab application.

5

Log out of the UPT tool and log back in as admin. Use caNanoLab as the application name when prompted at the UPT log in.

6

  1. Select User > Select an Existing User, and click Search. Select admin from the User list.
  2. Click View Details, then Associated Groups.
  3. Select Curator from the pre-defined group list and assign it to the user. Click Update Associations to commit the change.

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 maintain the passwords for user accounts. The UPT tool does not 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 caNanoLab-Support@ISB-CGC.org and request that the caNanoLab technical team give you a demonstration of the UPT tool in the context of the caNanoLab application.

Contacting Application Support

For any general information about the application, support, or to report a bug, contact caNanoLab-Support@ISB-CGC.org.

  • No labels