NCI Browsers Installation Instructions

Contents of this Page

NCI Browsers

This page documents the steps necessary to install and configure NCI Browsers on your local server.

An NCI Browser sits on top of the latest version of LexEVS Vocabulary repository. A LexEVS repository must be created and configured for NCI Term Browser to work.

To get and install the latest version of LexEVS repository, follow these steps:

You have to be either superuser or have root permissions when installing on Unix or Linux machines.
Download and install as documented on the LexEVS wiki
After installation load your desired vocabularies into the LexEVS repository. The NCI browsers will run without content in the LexEVS repository but it will not be practical since the browsers would have nothing to show or to search.

NCI Thesaurus Browser and NCI Term Browser

The NCI Term Browser hosting NCI vocabularies is available on the web.

To install a local instance, follow these steps:

Establish a LexEVS repository as described above.
Download the latest snapshot from SVN to a local folder, let's call it the {HOME_DIRECTORY}.
Modify the file "{HOME_DIRECTORY}/software/build/install.properties"

The file "install.properties" will have following two properties defined:
lex.evs.api.url (This is defined with the value 'null' for now)
lg.config.file (This is the location of the LexEVS configuration file)

Example:

lex.evs.api.url=null
lg.config.file=/usr/local/LexGrid/LexEVS/6.0/rc1instance2/resources/config/lbconfig.props

Create a file 'local.properties' in sub-directory "{HOME_DIRECTORY}/software/build"

The file "local.properties" will have following properties defined:
lex.evs.api.url (This is 'null' for now)
license_page_option (This is set to 'false' for now)
terminology.subset.download.url (This is set to 'null' for now)
ncit.url (URL which will be used to access this NCI Term Browser)
ncim.url (URL for the corresponding NCI Meta Browser, if you want it to show on main page)
jboss.server.hostname (Hostname where the the JBoss server is running, if you do not have one installed, you can use localhost. This Term browser will install an embedded one.)

Example:

lex.evs.api.url=null
license_page_option=false
terminology.subset.download.url=null
ncit.url={noformat}http://myserver.mayo.edu:19280/ncitbrowser{noformat}
ncim.url={noformat}http://myserver.mayo.edu:19280/ncimbrowser{noformat}
jboss.server.hostname=myserver.mayo.edu

Build the browser using following command:
```
 ant deploy:local:install
```

Test the installation:
- Open an internet browser to the NCIt URL (as defined in property file)
```
http://myserver.mayo.edu:19280/ncitbrowser
```
- Select the NCI Term Browser Link or the icon "NCI Term Browser" on the upper right close to the corner.
  You should see the list of terminologies loaded.
- Select an ontology, enter a term to search for, and click Search.

NCI Metathesaurus Browser

The NCI Meta browser hosting the NCI Metathesaurus is available on the web.

To install a local instance, follow these steps:

Establish a LexEVS repository as described above. Make sure it has the NCI Metathesaurus loaded.
Download the latest snapshot from SVN to a local folder, let's call it the {HOME_DIRECTORY}.
If the browser installation is based on the LexEVS 6.0 or above, you need to check whether there is a file "ehcache-1.2.2.jar" under the folder "{HOME_DIRECTORY}/trunk/software/ncimbrowser/lib/". If there is, remove it.
Look at the file "{HOME_DIRECTORY}/software/build/project.properties". The installation will need it, but we don't need to change it.

Create a file "{HOME_DIRECTORY}/software/build/local.properties" that looks like this:

 ### Application Entries ###
 log.level=DEBUG
 application.data.path=$\{user.home\}/apps/evs/ncimbrowser
 lex.evs.api.url=null
 lg.config.file=/usr/local/LexGrid/LexEVS/6.0/resources/config/lbconfig.props
 mail.smtp.server=mailfwd@example.com
 ncicb.contact.url=user@mail.nih.gov
 terminology.subset.download.url=null
 term.suggestion.application.url=null
 ncit.url={noformat}http://myserver.mayo.edu:19280/ncitbrowser/{noformat}
 license_page_option=false
 ### Local deployment Entries ###
 jboss.server.path=$\{user.home\}/apps/evs/jboss-5.1.0.GA-nci
 jboss.server.startscript=$\{user.home\}/apps/evs/jboss-5.1.0.GA-nci/bin/start_jboss
 jboss.server.stopscript=$\{user.home\}/apps/evs/jboss-5.1.0.GA-nci/bin/stop_jboss
 jboss.server.hostname=myserver.mayo.edu
 jboss.server.port=19280
 jboss.server.jndi.port=11299

You need to keep:

 _lex.evs.api.url=null_
 _terminology.subset.download.url=null_
 _term.suggestion.application.url=null_
 _license_page_option=false _

and adjust the rest of the properties as needed.

Build the browser using following command:
```
 ant deploy:local:install
```
unless you have already installed NCI Term Browser (any any other similar NCI browser or report writer) then use
```
 
ant deploy:local:upgrade
```
Test the installation. Go to the NCIm URL (as defined in property file)
```
http://myserver.mayo.edu:19280/ncimbrowser
```

Customizations

There are some optional customizations that can be done to your local installation.

To hide or change links on the main browser page, simple HTML changes can be made to the following JSP files:
welcome.jsp
welcome_other.jsp

To change the main icon (replacing the NCI Browser icon) replace the following files with desired images:
software/ncitbrowser/web/images/thesaurus_browser_logo.jpg
software/ncitbrowser/web/images/evs_termsbrowser_logo.gif

Note

Do not forget to restart your JBoss instance if you apply any customization and/or have to rebuild/deploy the
browser, otherwise you may not see the customizations.

Troubleshooting

If the Ant build does not execute or fails:
Make sure "ANT_HOME" is defined for the session you are working in.
For example, you may have to an environment variable like:
ANT_HOME=path-to-ant-installation-directory
or
export ANT_HOME=path-to-ant-installation-directory

If JBoss throws an "Out of memory" error:

Try following changes to JBoss' "run.conf" file.

This file is normally in the 'bin' directory of JBoss' installation.
However, if this is the embedded JBoss then "run.conf" is in work-directory/aaps/evs/jboss-5.1.0.GA-nci/bin/

Remove the parameter 'XX:ThreadStackSize'

Increase the heap size to 1 GB or more
The JAVA_OPTS should look like the following:
Before changes

JAVA_OPTS="-server -Xms256m -Xmx512m -XX:ThreadStackSize=128 -XX:SurvivorRatio=10 -XX:PermSize=128m -XX:MaxPermSize=128m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.awt.headless=true"

After changes

JAVA_OPTS="-server -Xms256m -Xmx1200m -XX:SurvivorRatio=10 -XX:PermSize=128m -XX:MaxPermSize=128m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.awt.headless=true"

If no data shows up in the browsers:
- Make sure that at least one ontology has been loaded correctly into LexEVS. You can check on loaded ontologies with the LexEVS 6.0 administration GUI.
- Enlarge the heap size by changing the "run.conf" file according to the above "Out of memory" instructions.
- Restart JBoss.
  Go to '${user.home}/apps/evs/jboss-5.1.0.GA-nci/bin/' and use commands './stop_jboss' and './start_jboss' to shutdown and launch JBoss.

Content

Space Tools