3 - Installing LexEVS 6.x Local Runtime

propswith

Contents of this Page

LexEVS 6.x Installation Links
Install Guide Main Page Overview Prerequisites and Platforms Local Runtime Local Runtime Command Line Distributed CTS2 Services URI Resolver Service LexEVS 6.0 Main Page LexEVS Current Release

Introduction

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

Preliminary considerations

BEFORE YOU BEGIN

LexEVS has been tested with the operating systems and hardware specified in the 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 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 if you should choose this route.
Complete the Downloading and Installing the LexEVS Local Runtime steps.

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. This is not recommended for a production environment.

LexEVS 6.x 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. This package includes the local runtime client and dependency JAR files listed in this table. LexEVS-install-6.5.0.6.jar LexEVS Local Runtime Jar lexbig.jar If you need the Local Runtime client, a JAR file with the LexEVS classes only can be found in {LEXEVS_HOME}/runtime-components/lexbig.jar. The core runtime, LexEVS API, loaders, and administrative utilities are included. Ships with the GUI installer. LexEVS Local Runtime 3rd Party Dependencies Includes code from other open source projects required by the LexEVS API. Available in the installer in the runtime-components/extLib directory after installation. 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-install-config-6.5.0.6.xml LexEVS Local Runtime Release Notes A list of resolved issues and enhancements provided in the major release. LexEVS 6.5.0.6 Release Notes
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.5.0.6.jar
3. Click the OK button to begin the installation. Note The only language currently supported is English.
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.
5. Review the license agreement of the LexEVS software. Select "I accept the terms of this license agreement." and click Next.
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.
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.
8. Once all the components have been installed, a [Finished] dialog will be displayed. Click Next.
9. A dialog with some help and urgent reminders will appear. Click Next.
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 instructions for Installing LexEVS 6.x Local Runtime (Optional Command Line Method). Click Done to complete the installation process.
11. Install the latest fixes. If you started with the 6.5.0.6 installer there are no additional fixes at this time.	GUI Installer for LexEVS Local Runtime A single download package with everything you need to install the Local Runtime in a graphical user environment. This package includes the local runtime client and dependency JAR files listed in this table. LexEVS-install-6.5.0.6.jar LexEVS Local Runtime Jar lexbig.jar If you need the Local Runtime client, a JAR file with the LexEVS classes only can be found in {LEXEVS_HOME}/runtime-components/lexbig.jar. The core runtime, LexEVS API, loaders, and administrative utilities are included. Ships with the GUI installer. LexEVS Local Runtime 3rd Party Dependencies Includes code from other open source projects required by the LexEVS API. Available in the installer in the runtime-components/extLib directory after installation. 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-install-config-6.5.0.6.xml LexEVS Local Runtime Release Notes A list of resolved issues and enhancements provided in the major release. LexEVS 6.5.0.6 Release Notes

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.x 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 database is MySQL. Specific versions are noted in the listing. Following installation of a database, you should follow these steps in order.

Step	Action
1. Configure Database Management System properties We provide an example of a MySQL configuration 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 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.x Local Runtime MySQL 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 is 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.
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.x 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 its 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 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.	Verify
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) Windows example: TestRunner.bat -v Unix example: ./TestRunner.sh -v Note The image shows the start of the test. If you use the Java runtime rather than the Java SDK at this point it will complain about tools.jar. Other debug errors may show up but these are just warnings.
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.

If all the tests pass then you have successfully installed the LexEVS Local Runtime. Congratulations!

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