View Source

{scrollbar:icons=false}

h1. {page-info:title}
{panel:title=Contents of this Page}
{toc:minLevel=2}
{panel}

h1. Introduction

This section provides requirements, instructions, and troubleshooting information for installing the LexEVS Distributed environment.

h2. Preliminary Considerations

* The [LexEVS 6.0 Supported Platforms to Include] are the same for this environment as they are for the Local Runtime.
* Before installing the LexEVS Distributed environment you must have a [WIP GET Installing LexEVS 6.0 Local Runtime] installed and working.
* It is not required that you load a terminology into the Local Runtime in order to complete the installation of the Distributed environment.  However, using the APIs in the Distributed environment requires that a terminology be loaded into the Local Runtime.
* The Distributed environment has additional [LexEVS 6.0 Prerequisite Software Supported to Include] beyond the Local Runtime.  The additional web application server does not have install steps given in this guide.  The web application server can be on the same server or a different server from the Local Runtime.
* Complete the [#Downloading and Installing LexEVS Distributed] steps below.

Once you have completed the additional prerequisite software install, the Distributed environment install steps, and the verification test as described in this guide then you should be ready to start using the Distributed features to meet the needs of your application.  Not counting prerequisite software products the installation and verification should not take more than 30 minutes.

h2. Downloading and Installing LexEVS Distributed

|| Step || Action ||
| 1. Download the latest version of the LexEVS Distributed WAR file from the right.  You have a choice between WAR files tailored for JBoss or Apache Tomcat installations.  The location you have chosen to save this on your computer will be referred to as the {{SAVE_DIRECTORY}}.  Our command examples will use {{scratch}} as this directory.
{info:title=Note}Access to the downloads does not require an account.  If you are having trouble downloading files then you may need to disable pop-up blockers or check any firewall settings at your site.{info} | {include:LexEVS 6.0 Distributed Downloads to Include} |
| 2. Shut down your application or servlet container.  This presumes that you have already installed a web server as outlined in the [LexEVS 6.0 Prerequisite Software Supported to Include].  The command to do the shut down will be web server specific.  See the documentation for your web server for information on how to do this.  There may be many alternatives.
JBoss example:
* Windows:
{code}
{{shutdown.bat -S}}
{code}
* Unix:
{code}
{{./shutdown.sh -S}}
{code}
If you experience Java errors then the server may already be down. | !jboss_shutdown.PNG|alt="Shutting down the JBoss server."! |
| 3. Rename the WAR file. These files are distributed with an application server designation in  their name for clarity while downloading them.  
Change to the {{SAVE_DIRECTORY}} and rename the file, like this:
{code}
rename {SAVE_DIRECTORY}/lexevsapi6.0.{WEB_SERVER}.war {SAVE_DIRECTORY}/lexevsapi60.war
{code}
JBoss example: 
* Windows: \\
{code}
rename c:\scratch\lexevsapi60.jboss.war lexevsapi60.war
{code}
* Unix: \\
{code}
move /scratch/lexevsapi60.jboss.war lexevsapi60.war
{code}
{info:title=Note}Consider other names as well.  Many application  servers use the deployed name as part of the URL, so if you would rather  it be a different name then you should rename the WAR file to that.{info} | !Jboss_rename.PNG|alt=""! |
| 4. Copy the WAR file to the appropriate web application server directory, like this:
{code}
copy {SAVE_DIRECTORY}\lexevsapi60.war {WEB_SERVER_HOME}\{DEPLOYMENT_HOME}
{code}
...where {{SAVE_DIRECTORY}} is the location of the downloaded file.
{{WEB_SERVER}} is the brand of the web server.
{{WEB_SERVER_HOME}} is your application server home directory.
{{DEPLOYMENT_HOME}} is the Web Archive deployment directory for your application server.
JBoss example:
* Windows:
{code}
copy c:\scratch\lexevsapi60.war c:\jboss-5.1.0.GA\server\default\deploy
{code}
Unix:
{code}
copy /scratch/lexevsapi60.war /jboss-4.0.5.GA/server/default/deploy}} | !Copy_evs_war.PNG|alt=""!
{code} |
| 5. Create a text file named {{lexevs.properties}} in the {{{WEB_SERVER_CLASSPATH}}} to set the location of the LexEVS configuration.  The {{{WEB_SERVER_CLASSPATH}}} is a location along the class path for your web application server.  This whole path including the file name will be called {{{LEXEVS_PROPERTIES_HOME}}} for the rest of these instructions.JBoss example:
* Windows: 
{code}
c:\jboss-5.1.0.GA\server\default\conf\lexevs.properties
{code}
* Unix: 
{code}
/jboss-5.1.0.GA/server/default/conf/lexevs.properties
{code}
Set {{LG_CONFIG_FILE}} to the path of the lbconfig.props file of your LexEVS installation like this: 
{code}
LG_CONFIG_FILE={LEXEVS_HOME}\resources\config\lbconfig.props
{code}
...where {{LexEVS_HOME}} is the install directory of LexVES.
Copy/paste the examples below as a starting point for this file:
* Windows:
{code}
LG_CONFIG_FILE=c:\\LexEVS\\6.0\\resources\\config\\lbconfig.props
{code}
{info:title=Note}he back slash escape character required for a Windows, Java environment.{info}
* Unix:
{code}
LG_CONFIG_FILE=/LexEVS/6.0/resources/config/lbconfig.props}} | !Create_lexevs_properties.PNG|alt=""! 
{code} |
| 6. *(OPTIONAL)* The {{lexevs.properties}} file is also used to add security for any coding scheme.  This is not a  highly used function, but may be required if your service is publicly  hosting a proprietary terminology.  For each coding scheme a security  implementation class name can be set to enable security like this: 
{code}
{CODING_SCHEME_NAME}={SECURITY_IMPLEMENTATION}
{code}
...where {{CODING_SCHEME_NAME}} is the name or URI of the terminology.
{{SECURITY_IMPLEMENTATION}} is a class that implements the interface gov.nih.nci.system.dao.security.DAOSecurity.
For all ways of accessing the coding scheme, security must be set up.  The example at the right shows access by *Name, URI, and Formal Name*, but others are possible too.Note:Coding schemes can be added or changed later after a coding scheme or terminology is loaded into LexEVS. | {code}
MedDRA=gov.nih.nci.system.dao.security.MedDRASecurity
 urn\:oid\:2\.16\.840\.1\.113883\.6\.163=gov.nih.nci.system.dao.security.MedDRASecurity
 Medical\ Dictionary\ for\ Regulatory\ Activities\ Terminology\ \(MedDRA\)=gov.nih.nci.system.dao.security.MedDRASecurity
{code} |
| 7. Adjust the {{properties-service.xml}} file.This file is likely to be found in the {{WEB_SERVER_HOME}}{{DEPLOYMENT_HOME}} directory but may be different for some servers.
JBoss example:
* Windows: 
{code}
c:\jboss-5.1.0.GA\server\default\deploy\properties-service.xml
{code}
* Unix:
{code}
/jboss-5.1.0.GA/server/default/deploy/properties-service.xml
{code}
Add a line to the file in the "System Properties Service" section where other properties are set like this:
{code}
<attribute name="Properties">org.LexGrid.LexBIG.caCore.Properties={LEXEVS_PROPERTIES_HOME}</attribute>
{code}
...where {{LEXEVS_PROPERTIES_HOME}} is the location and file name of {{lexevs.properties}} established in a previous step.
In Tomcat place the file in the  {{/webapps/lexevsapi60/WEB-INF/classes}} directory.  Edit the {{catalina.sh}} file in {{<tomcat root>/bin/}} adding to the {{JAVA_OPTS \-Xmx1052m  \-XX:MaxPermSize=256m"}}
...so that this line in {{catalina.sh:}}:
{code}
JAVA_OPTS="$JAVA_OPTS \-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
{code}
Should look like this: 
{code}
JAVA_OPTS="$JAVA_OPTS \-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \-Xmx1052m \-XX:MaxPermSize=256m"
{code}
JBoss example:
{code}
<attribute name="Properties">
org.LexGrid.LexBIG.caCore.Properties={LEXEVS_PROPERTIES_HOME}
</attribute>
{code]
...is added to this file between the {{<mbean>}} tags.
 The back slash escape character is NOT required for {{LEXEVS_PROPERTIES_HOME}}.
{info:title=Note}In some server installations you may not have authority to modify this file.  In that case you can simply move thelexevs.propertiesfile somewhere on the web application servers class path.{info} | !Jboss_properties_service.PNG|alt=""! |

h2. Testing LexEVS Distributed

|| Step || Action ||
| 1. Start your application or servlet container if it is  not already started.  The start command will be web server specific.   See the documentation for your web server for information on how to do  this.
JBoss example:
* Windows: 
{code}
Run.bat \-c default
{code}
* Unix:
{code}
./Run.sh \-c default}} | [!Jboss_start.PNG|alt=""!
{code} | 
| 2. Verify the installation by opening a browser to:
{code}
http://{SERVER_ADDRESS}/{WAR_FILE_DEPLOYED}
{code}
... where {{SERVER_ADDRESS}} is the address of your server (domain and optionally the port number).
 {{WAR_FILE_DEPLOYED}} is the name of the WAR file you placed in the server directories for deployment.
For example:
{{http://localhost:8080/lexevsapi60}} 
If you are using {{localhost}} then your browser must be running on the same server as LexEVS. | !EVS_Home.PNG
alt=""! |
If you see the Enterprise Vocabulary Services "Welcome to LexEVS" web  page then you have successfully installed the LexEVS Distributed. *Congratulations\!*

h2. Troubleshooting

* If the Local Runtime environment is properly installed and tested then the Distributed environment should have few problems.
* If you receive deployment errors in JBoss and are unable to see  the EVS home page then you may not have configured the properties  attribute in JBoss's properties-service.xml.
* You may also need to adjust the path in lexevs.properties where lbconfig.props location is defined.
* We recommend no threading limits less than 512mb being applied  when starting JBoss. (These would usually be configured as a JAVA_OPTS  variable in a run.conf or similar file and would be set as follows:  \-Xss512M )
* We recommend a minimum heap size of \-Xmx750m when starting  JBoss and about 1000m per million entities loaded.  (Also a JAVA_OPTS  variable)
* We recommend a minimum Perm Gen size of 256m. \\
{scrollbar:icons=false}