Page History

Versions Compared

Old Version 1

changes.mady.by.user Unknown User (wileyal)

Saved on Dec 04, 2011

compared with

New Version 2

changes.mady.by.user Unknown User (wileyal)

Saved on Jan 02, 2012

Key

This line was added.
This line was removed.
Formatting was changed.

Wiki Markup
Introduction This section provides requirements, instructions, and troubleshooting information for installing a LexEVS Local Runtime. Preliminary considerations \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Warning.jpg]\\ BEFORE YOU BEGIN \| LexEVS has been tested with the operating systems and hardware specified in the [Supported Platforms\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Supported_Platforms]. While LexEVS is expected to run on many variations of hardware and software similar to the test platforms, results cannot be guaranteed. Before you begin you should check to make sure that your platform will support the software. \| * There are a number of [Prerequisite Software\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Prerequisite_Software_Supported] products that you must install to run a LexEVS Local Runtime on your platform. You must make sure that you have the proper software and versions, depending on which LexEVS environment you are installing. Do this now, for the Local Runtime designated prerequisite software, before continuing to the install steps. * As an option you may consider the command line install of a LexEVS Local Runtime for putting all the necessary files in place based on a pre-decided list of components to include. As noted in the last step of the GUI Installer for LexEVS Local Runtime, you can save a file that represents the choices you have made during the GUI install. This file can be used as-is or be edited and then fed into an install on another server. Follow the [steps for installing a LexEVS Local Runtime using the optional command line method\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Installing_LexEVS_6.0_Local_Runtime_%28optional_Command_Line_Method%29] if you should choose this route. * Complete the [Downloading and installing the LexEVS Local Runtime\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Installing_LexEVS_6.0_Local_Runtime#Downloading_and_installing_the_LexEVS_Local_Runtime] steps below. Once you have completed the prerequisite software install, the Local Runtime environment install steps, and the verification test as described in this guide then you should be ready to start programming using the API to meet the needs of your application. Not counting prerequisite software products the installation and verification should not take more than 60 minutes.\\ LexEVS QuickStart Install Follow this link to get things up and running quickly. Not recommended for a production environment. [LexEVS 6.0 Local Runtime Quick Start\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Quick_Start] Downloading and Installing the LexEVS Local Runtime \| Step \| Action \| \| 1. Download the latest version of the Local Runtime GUI install package from the right. The location you have chosen to save this on your computer will be referred to as the SAVE_DIRECTORY. Examples will use scratch as the directory.\\ Note: If you plan to install LexEVS Distributed or the LexEVS Grid Services then you must install matching versions in conjunction with the Local Runtime.\\ 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. \| +GUI Installer for LexEVS Local Runtime+\\ A single download package with everything you need to install the Local Runtime in a graphical user environment.\\ [LexEVS 6.0 Installer\|https://gforge.nci.nih.gov/docman/view.php/491/23711/LexEVS-install-6.0.jar]\\ +LexEVS Local Runtime Fixes+\\ Fixes to be downloaded and installed after the initial install:\\ 6.0.1 [JAR file\|https://gforge.nci.nih.gov/frs/download.php/9362/lbPatch.jar] Copy this file into the {LEXEVS_HOME}/runtime directory. See the [ReadMe\|https://gforge.nci.nih.gov/frs/shownotes.php?release_id=4243] for the latest information for about this release.\\ +LexEVS Local Runtime Release Notes+\\ An optional download if you want to see the resolved issues and enhancements provided in the primary release. Readmes will contain information for fix releases.\\ [LexEVS 6.0 Release Notes\|https://gforge.nci.nih.gov/docman/view.php/491/23714/lexevsapi60_notes.html]\\ +LexEVS Local Runtime Command Line Install+\\ An XML file allowing the user to install in a command line environment. This file can be generated by the GUI installer or downloaded here.\\ [LexEVS 6.0 Command Line Install XML\|https://gforge.nci.nih.gov/docman/view.php/491/23701/LexEVS-install-config-6.0.xml]\\ +LexEVS Local Runtime Environment+\\ A seperate archive in Java jar format including the LexEVS classes only. The core runtime, LexEVS API, loaders, and administrative utilities are included. Ships with the GUI installer above.\\ [LexEVS 6.0 Runtime Jar\|https://gforge.nci.nih.gov/docman/view.php/491/23712/lexbig.jar]\\ +LexEVS Local Runtime 3rd Party Dependencies+\\ Includes third party, open source code required by the LexEVS API. These ship with the GUI installer above.\\ [LexEVS 6.0 Runtime dependencies\|https://gforge.nci.nih.gov/docman/view.php/491/23710/LexEVS_localRuntime_dependencies.jar] \| \| 2. Using a file explorer, navigate to the SAVE_DIRECTORY. Double Click on the downloaded JAR file. This will launch the install wizard.\\ As an alternative to a file explorer, use a command prompt. Change to the SAVE_DIRECTORY:\\ {_}cd {SAVE_DIRECTORY}{_} \\ \\ Then enter the command to begin the installation wizard: \\ {_}java \-jar LexEVS-install-{version}.jar{_} \\ where _{version}_ is the version you downloaded \\ \\ For example: \\ java \-jar LexEVS-install-6.0.jar \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:LexEVS_60_install_dir.PNG] \| \| 3. Click the OK button to begin the installation.\\ Note: The only language currently supported is English. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Language_Selection.jpg] \| \| 4. After the initial welcome screen, the release notes for the LexEVS distribution are displayed. Once you have read through the release notes click the Next button. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Release_Notes.jpg] \| \| 5. Review the license agreement of the LexEVS software. Select "I accept the terms of this license agreement." and click Next. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:License_page_installer.PNG] \| \| 6. Enter the path where you would like the LexEVS software installed. This will be referred to as LEXEVS_HOME throughout the remaining instructions.\\ Note: In any operating system it is NOT recommended to use spaces in the install path. You will be better off if you do not use the default "Program Files" path in Windows.\\ Click the Next button.\\ Note: If the directory does not exist, the program will prompt to proceed with creating the new directory. If the directory does exist, the program will prompt to overwrite the directory and files that may be contained within it. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Izpack_install_dir.PNG] \| \| 7. Select the components to be installed. The components "Product Information" and "Runtime and Administration Toolkit" are required and cannot be unchecked. The remaining components are optional. Clicking on individual components will display a description of that component.\\ Once components have been selected click Next. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Select_packs_install.PNG] \| \| 8. Once all the components have been installed, a \[Finished\] dialog will be displayed. Click Next. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Finish_Prompt.jpg] \| \| 9. A dialog with some help and urgent reminders will appear. Click Next. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Finish_Readme.png] \| \| 10. The last step of the installation wizard provides the ability to generate a command line installation configuration XML file that can be used on other servers. This installation script can be used to install LexEVS without the wizard that you just went through. If you want to generate this file then click the Generate an automatic installation script button. This will have no effect on the current installation. For more information look at the optional [command line install\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Installing_LexEVS_6.0_Local_Runtime_%28optional_Command_Line_Method%29] instructions.\\ Click Done to complete the installation process. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Izpack_Auto_install_script.PNG] \| \| 11. Install the latest fixes.\\ Select the latest fixes available on the right and install them as instructed. \| +GUI Installer for LexEVS Local Runtime+\\ A single download package with everything you need to install the Local Runtime in a graphical user environment.\\ [LexEVS 6.0 Installer\|https://gforge.nci.nih.gov/docman/view.php/491/23711/LexEVS-install-6.0.jar]\\ +LexEVS Local Runtime Fixes+\\ Fixes to be downloaded and installed after the initial install:\\ 6.0.1 [JAR file\|https://gforge.nci.nih.gov/frs/download.php/9362/lbPatch.jar] Copy this file into the {LEXEVS_HOME}/runtime directory. See the [ReadMe\|https://gforge.nci.nih.gov/frs/shownotes.php?release_id=4243] for the latest information for about this release.\\ +LexEVS Local Runtime Release Notes+\\ An optional download if you want to see the resolved issues and enhancements provided in the primary release. Readmes will contain information for fix releases.\\ [LexEVS 6.0 Release Notes\|https://gforge.nci.nih.gov/docman/view.php/491/23714/lexevsapi60_notes.html]\\ +LexEVS Local Runtime Command Line Install+\\ An XML file allowing the user to install in a command line environment. This file can be generated by the GUI installer or downloaded here.\\ [LexEVS 6.0 Command Line Install XML\|https://gforge.nci.nih.gov/docman/view.php/491/23701/LexEVS-install-config-6.0.xml]\\ +LexEVS Local Runtime Environment+\\ A seperate archive in Java jar format including the LexEVS classes only. The core runtime, LexEVS API, loaders, and administrative utilities are included. Ships with the GUI installer above.\\ [LexEVS 6.0 Runtime Jar\|https://gforge.nci.nih.gov/docman/view.php/491/23712/lexbig.jar]\\ +LexEVS Local Runtime 3rd Party Dependencies+\\ Includes third party, open source code required by the LexEVS API. These ship with the GUI installer above.\\ [LexEVS 6.0 Runtime dependencies\|https://gforge.nci.nih.gov/docman/view.php/491/23710/LexEVS_localRuntime_dependencies.jar] \| What's inside Now that you have the basic Local Runtime placed into LEXEVS_HOME on your server, you may want to take the time to see what's inside. This is an optional part of the install. Go to the [LexEVS 6.0 Local Runtime Installation directory Guide\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Installation_directory_Guide] to discover the contents of each of the sub directories in LEXEVS_HOME. Configuring the LexEVS environment The LexEVS Local Runtime can be configured to work with many different databases, however, the recommended databases are MySQL or PostgreSQL. Specific versions are noted in the [prerequisite software\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Prerequisite_Software_Supported]. Following installation of a database of your choice you should follow these steps in order. \| Step \| Action \| \| 1. Configure Database Management System properties\\ We provide examples of MySQL and PostgreSQL configurations to optimize a database for LexEVS.\\ Note: It is considered beyond the scope of these install instructions to address database setup and administration. However, proper database configuration is critical to the performance and long-term health of the LexEVS environment. System administrators should consult the MySQL or PostgreSQL documentation to determine settings that are appropriate to the host machine and environment. Tuning should be performed prior to loading vocabularies. {_}At a minimum, users must create a target database (see the next step) on the database server and provide user credentials for creating, deleting, and writing to tables._ \| MySQL properties\\ We highly recommend optimizing the behavior of the MySQL database server by changing the set of properties in the following link.\\ [LexEVS 6.0 Local Runtime MySQL Properties Guide\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_MySQL_Properties_Guide]\\ PostgreSQL properties\\ Optimizations for the Postgres DBMS are at the following link.\\ [LexEVS 6.0 Local Runtime PostgresSQL Properties Guide\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_PostgresSQL_Properties_Guide] \| \| 2. Create a database\\ LexEVS does not create a database for you. You must do this as the administrator of your database management system. \| Consult database management system documentation. We provide an example and a recommendation for MySQL. LexEVS must have access to a user with rights to create, update and delete tables. \| \| 3. Make sure the JDBC driver in place \| The java software interface for a given supported database must be available in the <install-root>/runtime/sqlDrivers directory * Check {LEXEVS_HOME}\runtime\sqlDrivers to see if the appropriate driver for your database is there. Licensing restrictions prevent some drivers, like those from MySQL, from being shipped with LexEVS. * MySQL driver can be downloaded from [MySQL downloads\|http://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.6/mysql-connector-java-5.1.6.jar]. \| \| 4. Modify the LexEVS configuration file\\ Update the LexEVS service properties file {LEXEVS_HOME}/resources/config/lbconfig.props\\ with connection and database settings\\ Note: This file contains properties controlling the behavior of the LexEVS Local Runtime. You must at least adjust the database configuration values for LexEVS within this file. \| The lbconfig.props file has the latest documentation embedded inside of it. lbconfig.props should be considered authoritative if there is a difference between the documentation written here and that contained in lbconfig.props.\\ You may open that file now and use the documentation within it to configure LexEVS.\\ The following link describes all of the property settings available for configuring LexEVS. It may have additional descriptive information beyond that found within lbconfig.props. It is useful but not necessary to a successful install.\\ [LexEVS 6.0 Local Runtime Configuration File Settings\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Configuration_File_Settings] \| \| 5. Set DB_PRIMARY_KEY_STRATEGY\\ Take extra care to consider this parameter in the configuration file. The value for the parameter may not be optimal for loading terminologies. You must change it's value before any LexEVS operations. Once there have been any operations you can not reset this parameter without deleting the database and recreating it. \| See the [parameter settings\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Configuration_File_Settings] documentation for more information. \| Testing the LexEVS Local Runtime This Local Runtime installation provides a test suite to verify the environment. Before running these tests the Local Runtime and databases must already be configured. \| Step \| Action \| \| 1. Your database management system and your web container must be running. This should already be true but if you get connection errors then it is usually due to this. \| \| \| 2. In a command prompt window change to the test directory:\\ {_}cd {LEXEVS_HOME}\test{_}\\ \\ Run the TestRunner utility to start the test process:\\ _> TestRunner.{ext} \-v{_}\\ where _{ext}_ is the extension appropriate for your operating system (bat for Windows, sh for Unix) \\ \\ For example: \\ Windows: \\ TestRunner.bat \-v \\ Unix: \\ ./TestRunner.sh \-v\\ Note: The image shows the start of the test. If you use the Java runtime rather than the SDK at this point it will complain about tools.jar. Other debug errors may show up but these are just warnings. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Start_Test.PNG] \| \| 3. Each test section should have \[OK\] printed after it. If so then that test passed. If you see \[FAIL\] after a test then you will need to look into the error. When it says BUILD SUCCESSFUL at the end this simply means that the test script ran to the end. \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:End_Test.PNG] \| If all the tests pass then you have successfully installed the LexEVS Local Runtime. Congratulations\!\\ \| [\|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Note.jpg]\\ NOTE \| The other options for this test script run a very large set of jUnits. The use of these is documented in the script comments. Not recommended for most users \| Troubleshooting * If you use a space in the name of the path to install LexEVS, that is LEXEVS_HOME, you might get errors from the underlying database during runtime. It it highly recommended that you do not use a space in the path. * Upgrading LexEVS may require reloading content. Be sure to read the release notes for each LexEVS release before installing the latest version. Preserve configuration files and indexes unless instructed to reload or do otherwise in the release notes. These files include lbconfig.props, registry.xml and the entire lbIndex directory in the resources directory. Note that the names of those last two files can be altered by variables in the lbconfig.props file. * LexEVS loads of content are generally handled in a robust manner. Failed loads clean up after themselves relatively well when database management systems are properly configured to allow database drop functions by LexEVS. However, exiting the application in the middle of a load may cause unpredictable results. Errors will be detected for some loads and they will be listed as PENDING in any API call to the coding scheme metadata. They can be removed if this is the case, and the user can restart the load. Other steps may need to be taken if this doesn’t work, including dropping databases as the DBA, deleting the index file for the offending terminology, and editing the registry.xml and metadata.xml files by hand. A quick, dirty solution is to drop all databases and delete all configuration files except lbconfig.props. * Know when to scale database management systems for management of large terminologies. Administrators who load very large terminologies, such as the NCI Metathesaurus in single table mode, will experience very long delays while the deletion process completes. * LexEVS is no longer distributed with a Java MySQL driver due to licensing concerns. If LexEVS reports an error concerning establishing a connection to the MySQL server yet the MySQL command line interface is able to connect, an adjustment in the version of Connector/J may be required. ** The latest version of Connector/J is available from MySQL.org. The new jar should be placed in the {LEXEVS_HOME}/runtime/sqlDrivers/ directory. If you are changing drivers remove the existing driver jar file to ensure that the class loader does not incorrectly load the older driver file. * If the user experiences slow performance with MySQL when loading or accessing terminologies then a review of the suggested configuration parameters for the database management system is recommended. Pay particular attention to the MySQL values.

Wiki Markup

*Introduction*

This section provides requirements, instructions, and troubleshooting information for installing a LexEVS Local Runtime.

*Preliminary considerations*
| [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Warning.jpg]\\
*BEFORE   YOU BEGIN* | LexEVS has been tested with the   operating systems and hardware specified in the [Supported   Platforms|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Supported_Platforms]. While LexEVS is expected to run on many variations of   hardware and software similar to the test platforms, results cannot be   guaranteed. Before you begin you should check to make sure that your platform   will support the software. |
* There are a number of [Prerequisite Software|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Prerequisite_Software_Supported] products that you must install to      run a LexEVS Local Runtime on your platform. You must make sure that you      have the proper software and versions, depending on which LexEVS      environment you are installing. Do this now, for the Local Runtime      designated prerequisite software, before continuing to the install steps.

* As an option you may consider the command line install      of a LexEVS Local Runtime for putting all the necessary files in place      based on a pre-decided list of components to include. As noted in the last      step of the GUI Installer for LexEVS Local Runtime, you can save a file      that represents the choices you have made during the GUI install. This      file can be used as-is or be edited and then fed into an install on      another server. Follow the [steps for installing a LexEVS Local Runtime using the      optional command line method|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Installing_LexEVS_6.0_Local_Runtime_%28optional_Command_Line_Method%29] if you should choose this route.

* Complete the [Downloading      and installing the LexEVS Local Runtime|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Installing_LexEVS_6.0_Local_Runtime#Downloading_and_installing_the_LexEVS_Local_Runtime] steps below.

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

*LexEVS QuickStart Install*

Follow this link to get things up and running quickly. Not recommended for a production environment. [LexEVS 6.0 Local Runtime Quick Start|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Quick_Start]

*Downloading and Installing the LexEVS Local Runtime*
| *Step* | *Action* |
| 1. Download the latest version of   the Local Runtime GUI install package from the right. The location you have   chosen to save this on your computer will be referred to as the SAVE_DIRECTORY.   Examples will use scratch as the directory.\\
*Note:* If you   plan to install LexEVS Distributed or the LexEVS Grid Services then you must   install matching versions in conjunction with the Local Runtime.\\
*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. | +GUI Installer for LexEVS Local   Runtime+\\
A single download package with everything you need to   install the Local Runtime in a graphical user environment.\\
[LexEVS 6.0 Installer|https://gforge.nci.nih.gov/docman/view.php/491/23711/LexEVS-install-6.0.jar]\\
+LexEVS Local Runtime Fixes+\\
Fixes to be downloaded and installed after the initial   install:\\
*6.0.1* [JAR file|https://gforge.nci.nih.gov/frs/download.php/9362/lbPatch.jar] Copy this file into the   {LEXEVS_HOME}/runtime directory. See the [ReadMe|https://gforge.nci.nih.gov/frs/shownotes.php?release_id=4243] for the latest information for about   this release.\\
+LexEVS Local Runtime Release Notes+\\
An optional download if you want to see the resolved   issues and enhancements provided in the primary release. Readmes will contain   information for fix releases.\\
[LexEVS 6.0 Release Notes|https://gforge.nci.nih.gov/docman/view.php/491/23714/lexevsapi60_notes.html]\\
+LexEVS Local Runtime Command Line   Install+\\
An XML file allowing the user to install in a command line   environment. This file can be generated by the GUI installer or downloaded   here.\\
[LexEVS 6.0 Command Line Install XML|https://gforge.nci.nih.gov/docman/view.php/491/23701/LexEVS-install-config-6.0.xml]\\
+LexEVS Local Runtime Environment+\\
A seperate archive in Java jar format including the LexEVS   classes only. The core runtime, LexEVS API, loaders, and administrative   utilities are included. Ships with the GUI installer above.\\
[LexEVS 6.0 Runtime Jar|https://gforge.nci.nih.gov/docman/view.php/491/23712/lexbig.jar]\\
+LexEVS Local Runtime 3rd Party   Dependencies+\\
Includes third party, open source code required by the   LexEVS API. These ship with the GUI installer above.\\
[LexEVS 6.0 Runtime dependencies|https://gforge.nci.nih.gov/docman/view.php/491/23710/LexEVS_localRuntime_dependencies.jar] |
| 2. Using a file explorer, navigate   to the SAVE_DIRECTORY. Double Click on the downloaded JAR file. This will   launch the install wizard.\\
As an alternative to a file   explorer, use a command prompt. Change to the SAVE_DIRECTORY:\\
  *{_}cd {SAVE_DIRECTORY}{_}* \\
  \\
 Then enter the command to begin the installation wizard: \\
  *{_}java \-jar LexEVS-install-{version}.jar{_}* \\
 where _{version}_ is the version you downloaded \\
  \\
 For example: \\
 java \-jar LexEVS-install-6.0.jar | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:LexEVS_60_install_dir.PNG] |
| 3. Click the *OK* button to   begin the installation.\\
*Note:* The   only language currently supported is English. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Language_Selection.jpg] |
| 4. After the initial welcome   screen, the release notes for the LexEVS distribution are displayed. Once you   have read through the release notes click the *Next* button. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Release_Notes.jpg] |
| 5. Review the license agreement of   the LexEVS software. Select "*I accept the terms of this license   agreement.*" and click *Next*. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:License_page_installer.PNG] |
| 6. Enter the path where you would   like the LexEVS software installed. This will be referred to as LEXEVS_HOME   throughout the remaining instructions.\\
*Note:* In any   operating system it is *NOT* recommended to use spaces in the install   path. You will be better off if you do not use the default "Program   Files" path in Windows.\\
Click the *Next* button.\\
*Note:* If the   directory does not exist, the program will prompt to proceed with creating   the new directory. If the directory does exist, the program will prompt to   overwrite the directory and files that may be contained within it. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Izpack_install_dir.PNG] |
| 7. Select the components to be   installed. The components "*Product Information*" and "*Runtime   and Administration Toolkit*" are required and cannot be unchecked.   The remaining components are optional. Clicking on individual components will   display a description of that component.\\
Once components have been selected   click *Next*. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Select_packs_install.PNG] |
| 8. Once all the components have   been installed, a \[Finished\] dialog will be displayed. Click *Next*. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Finish_Prompt.jpg] |
| 9. A dialog with some help and   urgent reminders will appear. Click *Next*. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Installation_Finish_Readme.png] |
| 10. The last step of the   installation wizard provides the ability to generate a command line   installation configuration XML file that can be used on other servers. This   installation script can be used to install LexEVS without the wizard that you   just went through. If you want to generate this file then click the *Generate   an automatic installation script* button. This will have no effect on the   current installation. For more information look at the optional [command line install|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Installing_LexEVS_6.0_Local_Runtime_%28optional_Command_Line_Method%29] instructions.\\
Click *Done* to complete the   installation process. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Izpack_Auto_install_script.PNG] |
| 11. Install the latest fixes.\\
Select the latest fixes available   on the right and install them as instructed. | +GUI Installer for LexEVS Local   Runtime+\\
A single download package with everything you need to   install the Local Runtime in a graphical user environment.\\
[LexEVS 6.0 Installer|https://gforge.nci.nih.gov/docman/view.php/491/23711/LexEVS-install-6.0.jar]\\
+LexEVS Local Runtime Fixes+\\
Fixes to be downloaded and installed after the initial   install:\\
*6.0.1* [JAR file|https://gforge.nci.nih.gov/frs/download.php/9362/lbPatch.jar] Copy this file into the   {LEXEVS_HOME}/runtime directory. See the [ReadMe|https://gforge.nci.nih.gov/frs/shownotes.php?release_id=4243] for the latest information for about   this release.\\
+LexEVS Local Runtime Release Notes+\\
An optional download if you want to see the resolved   issues and enhancements provided in the primary release. Readmes will contain   information for fix releases.\\
[LexEVS 6.0 Release Notes|https://gforge.nci.nih.gov/docman/view.php/491/23714/lexevsapi60_notes.html]\\
+LexEVS Local Runtime Command Line   Install+\\
An XML file allowing the user to install in a command line   environment. This file can be generated by the GUI installer or downloaded   here.\\
[LexEVS 6.0 Command Line Install XML|https://gforge.nci.nih.gov/docman/view.php/491/23701/LexEVS-install-config-6.0.xml]\\
+LexEVS Local Runtime Environment+\\
A seperate archive in Java jar format including the LexEVS   classes only. The core runtime, LexEVS API, loaders, and administrative   utilities are included. Ships with the GUI installer above.\\
[LexEVS 6.0 Runtime Jar|https://gforge.nci.nih.gov/docman/view.php/491/23712/lexbig.jar]\\
+LexEVS Local Runtime 3rd Party   Dependencies+\\
Includes third party, open source code required by the   LexEVS API. These ship with the GUI installer above.\\
[LexEVS 6.0 Runtime dependencies|https://gforge.nci.nih.gov/docman/view.php/491/23710/LexEVS_localRuntime_dependencies.jar] |
*What's inside*

Now that you have the basic Local Runtime placed into LEXEVS_HOME on your server, you may want to take the time to see what's inside. This is an optional part of the install. Go to the [LexEVS 6.0 Local Runtime Installation directory Guide|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Installation_directory_Guide] to discover the contents of each of the sub directories in LEXEVS_HOME.

*Configuring the LexEVS environment*

The LexEVS Local Runtime can be configured to work with many different databases, however, the recommended databases are MySQL or PostgreSQL. Specific versions are noted in the [prerequisite software|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Prerequisite_Software_Supported]. Following installation of a database of your choice you should follow these steps in order.
| *Step* | *Action* |
| 1. Configure Database Management   System properties\\
We provide examples of MySQL and   PostgreSQL configurations to optimize a database for LexEVS.\\
*Note:* It is   considered beyond the scope of these install instructions to address database   setup and administration. However, proper database configuration is critical   to the performance and long-term health of the LexEVS environment. System   administrators should consult the MySQL or PostgreSQL documentation to   determine settings that are appropriate to the host machine and environment.   Tuning should be performed prior to loading vocabularies. *{_}At a minimum, users must create a target database (see the   next step) on the database server and provide user credentials for creating,   deleting, and writing to tables._* | *MySQL properties*\\
We highly recommend optimizing the   behavior of the MySQL database server by changing the set of properties in   the following link.\\
[LexEVS 6.0 Local Runtime MySQL Properties Guide|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_MySQL_Properties_Guide]\\
*PostgreSQL properties*\\
Optimizations for the Postgres   DBMS are at the following link.\\
[LexEVS 6.0 Local Runtime PostgresSQL Properties Guide|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_PostgresSQL_Properties_Guide] |
| 2. Create a database\\
LexEVS does not create a database   for you. You must do this as the administrator of your database management   system. | Consult database management system   documentation. We provide an example and a recommendation for MySQL. LexEVS   must have access to a user with rights to create, update and delete tables. |
| 3. Make sure the JDBC driver in   place | The java software interface for a   given supported database must be available in the   <install-root>/runtime/sqlDrivers directory
* Check {LEXEVS_HOME}\runtime\sqlDrivers to see if the appropriate        driver for your database is there. Licensing restrictions prevent some        drivers, like those from MySQL, from being shipped with LexEVS.
* MySQL driver can be        downloaded from [MySQL downloads|http://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.6/mysql-connector-java-5.1.6.jar]. |
| 4. Modify the LexEVS configuration   file\\
Update the LexEVS service   properties file {LEXEVS_HOME}/resources/config/lbconfig.props\\
 with connection and database settings\\
*Note:* This   file contains properties controlling the behavior of the LexEVS Local   Runtime. You must at least adjust the database configuration values for   LexEVS within this file. | The lbconfig.props file has the latest documentation embedded inside of it. lbconfig.props   should be considered authoritative if there is a difference between the   documentation written here and that contained in lbconfig.props.\\
You may open that file now and use   the documentation within it to configure LexEVS.\\
The following link describes all   of the property settings available for configuring LexEVS. It may have   additional descriptive information beyond that found within lbconfig.props.   It is useful but not necessary to a successful install.\\
[LexEVS 6.0 Local Runtime Configuration File Settings|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Configuration_File_Settings] |
| 5. Set DB_PRIMARY_KEY_STRATEGY\\
Take extra care to consider this   parameter in the configuration file. The value for the parameter may not be   optimal for loading terminologies. You must change it's value before any   LexEVS operations. Once there have been any operations you can not reset this   parameter without deleting the database and recreating it. | See the [parameter settings|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/LexEVS_6.0_Local_Runtime_Configuration_File_Settings] documentation for more   information. |
*Testing the LexEVS Local Runtime*

This Local Runtime installation provides a test suite to verify the environment. Before running these tests the Local Runtime and databases must already be configured.
| *Step* | *Action* |
| 1. Your database management system   and your web container must be running. This should already be true but if   you get connection errors then it is usually due to this. | |
| 2. In a command prompt window   change to the test directory:\\
*{_}cd {LEXEVS_HOME}\test{_}*\\
  \\
 Run the TestRunner utility to start the test process:\\
  *_> TestRunner.{ext} \-v{_}*\\
 where _{ext}_ is the extension appropriate for your operating system   (bat for Windows, sh for Unix) \\
  \\
 For example: \\
 Windows: \\
 TestRunner.bat \-v \\
 Unix: \\
 ./TestRunner.sh \-v\\
*Note:* The   image shows the start of the test. If you use the Java runtime rather than   the SDK at this point it will complain about tools.jar. Other debug errors   may show up but these are just warnings. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Start_Test.PNG] |
| 3. Each test section should have   \[OK\] printed after it. If so then that test passed. If you see \[FAIL\] after a   test then you will need to look into the error. When it says BUILD SUCCESSFUL   at the end this simply means that the test script ran to the end. | [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:End_Test.PNG] |
If all the tests pass then you have successfully installed the LexEVS Local Runtime. *Congratulations\!*\\
| [|https://cabig-kc.nci.nih.gov/Vocab/KC/index.php/Image:Note.jpg]\\
*NOTE* | The other options for this test   script run a very large set of jUnits. The use of these is documented in the   script comments. Not recommended for most users |
*Troubleshooting*
* If you use a space in the name of the path to install      LexEVS, that is LEXEVS_HOME, you might get errors from the underlying      database during runtime. It it highly recommended that you do not use a      space in the path.
* Upgrading LexEVS may require reloading content. Be sure      to read the release notes for each LexEVS release before installing the      latest version. Preserve configuration files and indexes unless instructed      to reload or do otherwise in the release notes. These files include      lbconfig.props, registry.xml and the entire lbIndex directory in the      resources directory. Note that the names of those last two files can be      altered by variables in the lbconfig.props file.
* LexEVS loads of content are generally handled in a      robust manner. Failed loads clean up after themselves relatively well when      database management systems are properly configured to allow database drop      functions by LexEVS. However, exiting the application in the middle of a      load may cause unpredictable results. Errors will be detected for some loads      and they will be listed as PENDING in any API call to the coding scheme      metadata. They can be removed if this is the case, and the user can      restart the load.
** Other steps may need to be taken if this doesn’t work,       including dropping databases as the DBA, deleting the index file for the       offending terminology, and editing the registry.xml and metadata.xml       files by hand.
** A quick, dirty solution is to drop all databases and       delete all configuration files except lbconfig.props.
* Know when to scale database management systems for      management of large terminologies. Administrators who load very large      terminologies, such as the NCI Metathesaurus in single table mode, will      experience very long delays while the deletion process completes.
* LexEVS is no longer distributed with a Java MySQL      driver due to licensing concerns. If LexEVS reports an error concerning      establishing a connection to the MySQL server yet the MySQL command line      interface is able to connect, an adjustment in the version of Connector/J      may be required.
** The latest version of Connector/J is available from       MySQL.org. The new jar should be placed in the       {LEXEVS_HOME}/runtime/sqlDrivers/ directory. If you are changing drivers       remove the existing driver jar file to ensure that the class loader does       not incorrectly load the older driver file.
* If the user experiences slow performance with MySQL      when loading or accessing terminologies then a review of the suggested      configuration parameters for the database management system is      recommended. Pay particular attention to the MySQL values.

Content

Space Tools

Versions Compared

Old Version 1

New Version 2

Key