NIH | National Cancer Institute | NCI Wiki  

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.