View Source

Welcome to the caNanoLab 2.4 Installation Guide.

Print the Guide
If you want to print or export content from the guide, refer to Printing and Exporting to Different Formats.

Topics in this document include:

Introduction to caNanoLab

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

Return to top

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 the following page:

http://www.mysql.com/downloads/workbench/

Product	Link
Java Software Development Kit (JDK) version 8.0 and set JAVA_HOME	http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
Wildfly version 8.2.0.Final	http://wildfly.org/downloads/
Jakarta Ant version 1.9.x and set ANT_HOME environment variable	http://archive.apache.org/dist/ant/binaries/
MySQL version 5.1.x	http://dev.mysql.com/downloads/mysql/5.1.html
Apache Maven 3.3.x or higher	https://archive.apache.org/dist/maven/maven-3

Return to top

Obtaining the caNanoLab Source Code

Downloads for caNanoLab are available at the caNanoLab GitHub Repository:

https://github.com/CBIIT/cananolab/releases

The caNanoLab Software License applies.

Return to top

Ant Build Properties

Setting Properties

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

Step 1. Extract caNanoLab

Download the following file:

https://github.com/CBIIT/cananolab/archive/refs/tags/2.4.0-qa6.zip

Extract the above file to a location on your local system, for example, C:\caNanoLab_2.3. and navigate into the “software” directory to reach the source. (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

Return to top

Step 2. Edit Ant Properties

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

Property

Description

file.repository.dir

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

Create this directory prior to starting the application, and ensure that the user who starts the Wildfly server has Write access. If working on Windows platform, use either double back slashes \\ or a single forward slash / as the file separator.

admin.email

The email address that receives requests for new user accounts, for example, the NCI CBIIT application support email for the NCI CBIIT installation, for example, NCIAppSupport@nih.gov.

ldap.authentication.enabled

A Boolean flag to indicate whether or not to use LDAP for user authentication. caNanoLab 2.1.1 and beyond does not support LDAP authentication. Set this to false.

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 that the user specified above, for example, go!234.

database.system.user

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

database.system.password

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

jboss.server.dir

The Wildfly server directory, for example:

C:/apps/wildfly-8.2.0.Final/standalone

Return to top

Installation and Deployment

Step 1. To migrate from caNanoLab 2.3 to caNanoLab 2.4

a Execute the following script:

https://github.com/CBIIT/cananolab/blob/2.4.0-qa6/software/cananolab-webapp/db-scripts/2.4.0/db_update_2.4.0.sql

Return to top

Step 2. caNanoLab installation instructions to upgrade to 2.3

a Follow these steps to deploy the caNanoLab application.

#

Action

1

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

If working on the Windows platform, use either double back slashes // or a single forward slash / as the file separator, 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>/software/cananolab-webapp/build.xml with the target dist.

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

C:\>cd C:\caNanoLab_2.3\software\cananolab-webapp
C:\caNanoLab_2.3\software\cananolab-webapp>ant dist

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 generated are also available in the following folder under <CANANOLAB_SOURCE>:

target/dist/cananolab-webapp/caNanoLab.war
target/dist/common/ApplicationSecurityConfig.xml
target/dist/common/mysql-connector-java-5.1.26.jar
target/dist/common/properties-service.xml
target/dist/common/bcprov-jdk15on-1.69.jar
target/dist/common/caNanoLab_modules.cli
target/dist/common/caNanoLab_setup.cli
target/dist/common/caNanoLab_deploy.cli

target/dist/common/wikihelp.properties

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="-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.

For a standalone server, pass in the JVM settings either as command line arguments when executing the $JBOSS_HOME/bin/standalone.sh script, or by declaring them in $JBOSS_HOME/bin/standalone.conf.
(For Windows users, the script to execute is %JBOSS_HOME%/bin/standalone.bat while the JVM settings can be declared in
%JBOSS_HOME%/bin/standalone.conf.bat.)

4

Create a new directory structure C:/local/content/caNanoLab/artifacts and move the following artifacts.

caNanoLab.war
bcprov-jdk15on-1.69.jar
mysql-connector-java-5.1.26.jar
caNanoLab_modules.cli
caNanoLab_setup.cli
caNanoLab_deploy.cli

Create a new directory structure C:/local/content/caNanoLab/config and move the following artifacts.

ApplicationSecurityConfig.xml
wikihelp.properties

5

Start JBoss application server in Standalone mode.

From <install-dir>/bin:

./standalone.sh --server-config=standalone-full.xml

The cli scripts assumes the CLI port is running at 19990. If it is different, update the port number at the second line in the script.

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= /local/content/caNanoLab/artifacts/caNanoLab_modules.cli and press <ENTER>.

Run the remaining caNanoLab_setup.cli and caNanoLab_deploy.cli that deploys the caNanoLab.

After successful completion, the following output appears in the window.

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

Return to top

c Restart the application server after the above step to migrate data is completed.

Verification

Once the deployment artifacts are deployed and the Wildfly application server is correctly configured, shutdown and restart 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.

Return to top