<?xml version="1.0" encoding="utf-8"?>
<html>

Introduction

This document is a subsection of the [Installation Guide].

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

Preliminary considerations

Unable to render embedded object: File (Warning.jpg) not found. 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 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.

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 <tt>SAVE_DIRECTORY</tt>. Our command examples will use <tt>scratch</tt> as this directory.

If you plan to install the LexEVS Remote API or the LexEVS Grid Services in conjunction then the Local Runtime version must match what you plan to install.

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. | :LexEVS_Local_Runtime_Downloads |

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

Unknown macro: {SAVE_DIRECTORY}

_*

Then enter the command to begin the installation wizard:

*_java jar LexEVS-install

Unknown macro: {version}

.jar_*

where _

_ is the version you downloaded

For example:

3. Click the OK button to begin the installation. Note: The only language currently supported is English.	[[Image:Installation_Language_Selection.jpg	frameless	center	600px
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.	[[Image:Installation_Release_Notes.jpg	frameless	center	600px
5. Review the license agreement of the LexEVS software. Select "I accept the terms of this license agreement." and click Next.	[[Image:License_page_installer.PNG	frameless	center	600px
6. Enter the path where you would like the LexEVS software installed. This will be referred to as <tt>LEXEVS_HOME</tt> 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. | [[Image:Install_path_installer.PNG | frameless | center | 600px |

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.	[[Image:Select_packs_install.PNG	frameless	center	600px
8. Once all the components have been installed, a [VKC:Finished] dialog will be displayed. Click Next.	[[Image:Installation_Finish_Prompt.jpg	frameless	center	600px
9. 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 [[Installing_LexEVS_Local_Runtime_(optional_Command_Line_Method)	[[Image:Installation_Complete_Window.jpg	frameless	center	600px

What's inside

This section describes the location and organization of installation materials. Following installation, many of the following hierarchy of files and directories will be available (some features are optionally installable):

(As located in the LexEVS installation root directory)

Directory	Description of content
<tt>/admin</tt>	Installed by default. This directory provides a centralized point for command line scripts that can be executed to perform administrative functions such as the loading, activation/deactivation, and removal of vocabulary resources.

Object code used to carry out these functions is included directly in the LexEVS runtime components. Source code is included in the <tt>/source</tt> directory in the <tt>lbAdmin-src.jar</tt> (described below). |

<tt>/doc</tt>	Optionally installed. This directory provides documentation related to LexEVS services, configuration, and execution. This guide is distributed in the <tt>/doc</tt> top-level directory.
<tt>/doc/javadoc</tt>	This directory provides documentation for model classes and public interfaces available to LexEVS programmers. Also included with each object representation is a UML-based model diagram that shows the object, its attributes and operations, and immediately linked objects. The diagrams work to provide clickable navigation through the javadoc materials.
<tt>/examples</tt>	Optionally installed. This directory provides a small number of example programs.

Refer to the <tt>README.txt</tt> file in this directory for instructions used to configure and run the example programs. The examples are intended to provide a limited interactive demonstration of LexEVS capabilities.

Source and object code for the example programs is provided under the <tt>/examples/org</tt> subdirectory. Source materials are also centrally archived under the <tt>/source</tt> directory in the file <tt>lbExamples-src.jar</tt>. |

<tt>/examples /resources</tt>	Contains sample vocabulary content for reference by the example programs; use the <tt>/examples/LoadSampleData</tt> command-line script to load for example code use or use one of the loaders in the /admin folder to load other content.
<tt>/gui</tt>	Optionally installed. This folder contains programs and supporting files to launch the LexEVS Graphical User Interface (GUI). The GUI provides convenient centralized access to administrative functions as well as support to test and exercise most of the LexEVS API.

The GUI is launched using a platform-specific script file in the <tt>/gui</tt> directory. The name of the platform (e.g. Windows, OSX, etc) is included in the file name.

Program source and related materials are centrally archived under the <tt>/source</tt> directory in the file <tt>lbGUI-src.jar</tt>. |

Default location for log files, which can be modified by the LOG_FILE_LOCATION entry in the <tt>lbconfig.props</tt> file (see next section).

<tt>/resources</tt>

Installed by default. This directory contains resources referenced and written directly by the LexEVS runtime. It should, in general, be considered off-limits to modify or remove the content of this directory without specific guidance and reason to do so. Files typically stored to this location include the vocabulary registry (tracking certain metadata for installed content) and indexes used to facilitate query over the installed content.

One file of particular interest in this directory is the <tt>/resources/config/lbconfig.props</tt> file. This file controls access to the database repository and other settings used to tune the LexEVS runtime behavior. Contents of this file should be set according to instructions provided by the LexEVS Administrator's Guide. |

<tt>/runtime</tt>

Installed by default. This directory contains a Java archive (.jar) file containing the combined object code of the LexEVS runtime, LexEVS administrative interfaces, and any additional code they are dependent on. All required code for execution of LexEVS administrative and runtime services is installed to this directory.

<tt>/runtime/lbPatch.jar</tt>

In the course of the product lifecycle, it is possible that smaller fixes will be introduced as a patch to the initially distributed runtime. Including this file in the classpath ensures automatic accessibility to the calling program without requiring adjustment. All patches are cumulative (there is at most one patch file introduced per release; all patch-level fixes are cumulative).

<tt>/runtime/lbRuntime.jar</tt>

This is the standard runtime file, including all LexEVS and dependency code required for program execution except for SQL drivers (see next). |

<tt>/runtime
/sqldrivers</tt>

The JDBC drivers used to connect to database repositories are not included in the <tt>lbRuntime.jar</tt>. Instead, the runtime scans this directory for the drivers to include. This can be overridden by path settings in the <tt>lbconfig.props</tt> file.

Note: while the LexEVS software package ships with JDBC drivers to certain open source databases such as PostgreSQL, this folder provides a mechanism to introduce updated drivers or to add drivers which are license restricted for additional supported database systems.

For example, the Oracle database is supported by the runtime environment. However, the drivers are not redistributed with the LexEVS software. To run against Oracle, an administrator would add a jar with the appropriate JDBC driver to this directory and then reference it in the <tt>lbconfig.props</tt> settings. MySQL, the main test base for LexEVS, also requires a restricted license driver. It's driver can be downloaded here: mysql-connector-java-5.1.6 |

<tt>/runtime-
components</tt>

Optionally installed. Due to license considerations for additional materials (as described by the <tt>license.pdf</tt> and <tt>license.txt</tt> files in the install directory), the cumulative runtime provided in the <tt>lbRuntime.jar</tt> is not redistributable.

This directory contains a finer grain breakdown of object code into logical components and 3rd party inclusions. All components are redistributable under their own license agreements, which are provided along with each archive.

The top-level of the <tt>/runtime-components</tt> directory contains all code produced for the LexEVS project in the <tt>lexbig.jar</tt>.

Note: These files are included as an alternative to the <tt>lbRuntime.jar</tt> for code execution and redistribution. There is no need to include any of these files in the Java classpath if you are already including the <tt>lbPatch.jar</tt> and <tt>lbRuntime.jar</tt> described above. |

<tt>/runtime- components/ext Lib</tt>	This subdirectory includes all 3rd party code redistributed with the LexEVS runtime, along with respective license agreements.
<tt>/source</tt>	Optionally installed. This directory provides central accessibility to Java source for all code developed for the LexEVS project.
<tt>/test</tt>	Optionally installed. This directory provides an automated test bucket that can be used by System Administrators to verify node installation. Note that the <tt>/runtime/config/lbconfig.props</tt> file must still be configured for database access prior to invoking the test bucket.

Testcases are launched via the TestRunner command-line script. Several reporting options are provided and are further described in the LexEVS Administrator's Guide. |

<tt>/uninstaller</tt>

Contains an executable jar that can be invoked by an administrator to uninstall files originally introduced by the LexEVS installation.

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 as noted in the prerequisite software. Following installation of a database of your choice you should follow these steps in order. The remaining text in this section is meant to help facilitate these steps.

Configure properties of your database software (MySQL and PostgreSQL examples shown below)
Create a database (commands for this are available in your database software documentation)
Obtain a JDBC driver for LexEVS to use when accessing the database.
- Check <tt>{LEXEVS_HOME}\runtime\sqlDrivers</tt> to see if the appropriate driver for your database is there. Due to licensing reasons we can not ship some drivers, such as the MySQL driver.
  - MySQL driver can be downloaded from Mysql driver mysql-connector 5.1.6.
Update the LexEVS <tt>lbconfig.props</tt> file (server properties) with connection and database settings

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.
The following tables provide settings that have been modified in database environments used during LexEVS development and adoption, and are provided for consideration by database administrators.

MySQL properties

At a minimum you should consider changing these properties controlling the behavior of the MySQL database server. These properties are usually located in the file <tt>{MYSQL_HOME}/my.ini</tt>.

Property Name	<center>Description</center>
<tt>innodb_flush_log_at_trx_commit</tt>	Flush the transaction logs at each commit.

Value: It is highly recommended that this option be set to '0' in Windows installations to improve load performance. |

<tt>innodb_additional_mem_pool_size</tt>

Additional memory pool that is used by InnoDB to store metadata information.

Value: 16M |

<tt>innodb_buffer_pool_size</tt>

Buffer pool used to cache both indexes and row data.

Value: 1G (consider going higher based on physical RAM available) |

<tt>tmp_table_size</tt>

Maximum size for internal (in-memory) temporary tables.

Value: 256M |

<tt>query_cache_size</tt>

Query cache is used to cache SELECT results and later return them without actually executing the same query once again.

Value: 64M |

<tt>sort_buffer_size</tt>

This buffer is allocated when MySQL needs to rebuild the index in REPAIR, OPTIMZE, ALTER table statements as well as in LOAD DATA INFILE into an empty table.

Value: 16M |
Note: MySQL can be passed a JDBC option for the Windows local environment that may improve perfomance 30 to 50%.

Try the following values in the lbconfig.props file for the DB_URL. This uses Windows Named Pipe function and avoids use of the TCP/IP protocol. It only works when connecting with a local iteration of the MySQL database on Windows.

<tt>DB_URL=jdbc:mysql:///<dbname>?socketFactory=com.mysql.jdbc.NamedPipeSocketFactory</tt>

There are some commands that we have found useful in this environment. You can investigate this database software more at the MySQL web site.

If you have root or administrator access to your server you can change the password for the <tt>root</tt> user ID if you have forgotten or lost it.

*mysqladmin -u root password {mypassword}

where {mypassword} is your new password
Creating a database within the software can be done via the command line. The software does not come, by default, with GUI administration. That command might look like this:

*mysqladmin -u root -p create {DBNAME}

where {DBNAME} is the name of your database needed for LexEVS to store data in. You will be prompted for your password before the database is created.

PostgreSQL properties

Modifying the posgresql.conf File for PostgreSQL

The file
Unknown macro: {PostgreSQL_HOME_DIRECTORY}
/posgresql.conf contains properties controlling the behavior of the PostgreSQL database server. |

Property Name	<center>Description</center>
<tt>shared_buffers</tt>	Number of shared buffers.

Value: 1000. |

The amount of memory in kilobytes allocated to working memory

Value: 51200. |

<tt>maintenance_work_mem</tt>

The amount of memory in kilobytes allocated to maintenance working memory.

Value: 512000. |

<tt>enable_seqscan</tt>

We set the 'enable_seqscan' to false to use always use an index versus a table scan.

Server properties

The next step is to configure LexEVS. This is wrapped up in editing one file, <tt>{LEXEVS_HOME}/resources/config/lbconfig.props</tt>.
This file contains properties controlling the behavior of the LexEVS Local Runtime.

Unable to render embedded object: File (Warning.jpg) not found. Warning	The <tt>lbconfig.props</tt> file has the latest documentation embedded inside of it. <tt>lbconfig.props</tt> should be considered authoritative if there is a difference between the documentation written here and that contained in <tt>lbconfig.props</tt>.

You may open that file now and use the documentation within it to configure LexEVS and skip the rest of this section, keeping in mind that the information here is useful but not necessary to a successful install. |

Below you will find an expanded overview of the options in this file. Options in <tt>BOLD</tt> must be modified so that LexEVS can properly use your database. They are also noted as required. There are many other options that you can change for performance reasons or alternative deployment scenarios, but you probably don't need to change them in a standard LexEVS installation. Some options can not be changed after you load terminologies into LexEVS. Now would be a good time to read about what is available to you.

Note: A single back slash '\' is not valid within the <tt>lbconfig.props</tt> file for file or directory paths (except within JDBC connection strings). When constructing file or directory paths you must use either a forward slash '/' or two backward slashes '
'.

Property Name	<center>Description</center>
<tt>DB_URL</tt>
<tt>DB_PREFIX</tt>	Required for Oracle databases: The prefix to use on all tables or databases that LexEVS creates. If your database is Oracle, you may not use this feature. Leave the value equal to nothing.

If you wish to run multiple LexEVS installations on the same database server, give them each a unique prefix.

Do not use dashes '-' in the DB_PREFIX value. Recommended characters are alphanumeric (a-z, 0-98) and underscore '_'.

The default is <tt>'lb'</tt>. |

<tt>DB_PARAM</tt>	Optional variable for passing extra database parameters. These will be appended to the end of the database connection string.
<tt>DB_DRIVER</tt>	Required: The Java class name that represents the driver that you wish to use with your database.

There are several options in the file as an example. |

Required: The database username. This account must have permission to add and remove tables, indexes, etc inside of this database.

This account is typically created during the installation of the database software and is not necessarily a system user ID. |

<tt>DB_PASSWORD</tt>	Required: The password for the database username.
<tt>LG_CONFIG_FILE</tt>	This is not actually a variable that you would set within this file. It is documented here for clarity of other variables that depend on this variable.

Normally, this variable is automatically set (at runtime) to the location of the lbconfig.props file that is being used by the runtime.

Alternatively, you can set the java system variable <tt>'LG_CONFIG_FILE'</tt> at system startup to point to the <tt>lbconfig.props</tt> file that you want LexEVS to use. Refer to additional documentation in the <tt>lbconfig.props</tt> file if you need to use this feature. |

This variable is the path that will be used to resolve any other relative (or unqualified) paths in the <tt>lbconfig.props</tt> file.

This variable is optional, and should usually be left blank.

If this variable is left blank, it will automatically be set (at runtime) to the location of the folder which contains the <tt>lbconfig.props</tt> file that the system was started with.

This variable can also be overridden by setting the java system variable <tt>'LG_BASE_PATH'</tt>.

The default value is blank. |

<tt>JAR_FILE_LOCATION</tt>

The path of the folder that contains your SQL drivers and LexEVS extensions (if you have any).

This value can be relative to the <tt>'LG_BASE_PATH'</tt> or absolute.

The default is <tt>'../../runtime'</tt> |

<tt>REGISTRY_FILE</tt>

The location of the file that will store information about all loaded terminologies.

This value can be relative to the <tt>'LG_BASE_PATH'</tt> or absolute.

The default is <tt>'registry.xml'</tt> |

<tt>INDEX_LOCATION</tt>

The folder where all LexEVS generated indexes will be stored. This folder can potentially be large (100+ GB) - depending on the terminologies loaded.

This value can be relative to the <tt>'LG_BASE_PATH'</tt> or absolute.

The default is <tt>'../lbIndex'</tt> |

<tt>MAX_CONNECTIONS_PER_DB</tt>

LexEVS maintains a pool of connections to each database that it connects to. This sets the limit on the number of connections that will be opened. You may want to set this to a higher value - 20 or so (depending on expected user load)

The default is 8. |

<tt>CACHE_SIZE</tt>

LexEVS maintains an internal cache of some information that it needs to query from the database to resolve queries. This controls the size of that cache. This cache does not hold entire user queries.

The default size is 500. |

<tt>ITERATOR_IDLE_TIME</tt>

The length of time to allow an unused (and unclosed) iterator to stay valid before it is closed (and its resources freed) by the system.

The default is 5 minutes. |

<tt>MAX_RESULT_SIZE</tt>

This controls the maximum number of results that a user can resolve at one time for the CodedNodeSets and CodedNodeGraphs.

This does not affect the total number of results that can be returned by an iterator, just the size that can be returned on the 'next' API call.

The default is 1000. |

<tt>LUCENE_MAX_CLAUSE_COUNT</tt>

The number of boolean 'clauses' Lucene will attempt to create for wildcard or Regular Expression queries. For very general queries on large ontologies, this will need to be set high.

The default is 40000. |

<tt>LOG_FILE_LOCATION</tt>

The path where LexEVS log files will be written.

This value can be relative to the <tt>'LG_BASE_PATH'</tt> or absolute.

The default is <tt>'../../logs'</tt> |

<tt>API_LOG_ENABLED</tt>

Setting API call logging to <tt>'true'</tt> will cause every method call to be printed to the log file.

The default is <tt>'false'</tt>. |

<tt>SQL_LOG_ENABLED</tt>

Setting SQL logging to <tt>'true'</tt> will cause every sql statement executed to be printed to the log file.

The default is <tt>'false'</tt>. |

<tt>DEBUG_ENABLE</tt>

Setting debug to <tt>'true'</tt> will give you more verbose logging information to debug problems. This should normally be set to <tt>'false'</tt> since debug logging causes a negative performance impact.

The default is <tt>'false'</tt>. |

<tt>LOG_CHANGE</tt>

Indicates when a new log file should be started. This can be set to <tt>'monthly', 'weekly'</tt> or <tt>'daily'</tt>.

This can also be set to a number which will cause it to start a new log file whenever it reaches the specified number of MB in size.

The default is 5 MB. |

<tt>ERASE_LOGS_AFTER</tt>

If <tt>LOG_CHANGE</tt> is set to <tt>'daily', 'weekly',</tt> or <tt>'monthly'</tt>, this variable instructs the logging service to remove log files that have not been written to in the specified amount of days.

If <tt>LOG_CHANGE</tt> is set to a number of MB then this variable specifies the number of old log files that will be kept.

The unit is treated as days regardless of the <tt>LOG_CHANGE</tt> value.

Cleanup will only occur on restart of the JVM.

The default is 5 files. |

<tt>EMAIL_ERRORS</tt>

Used to enable or disable e-mail notification of system errors and warnings. If you set this to <tt>'true'</tt>, you must set SMTP_SERVER and EMAIL_TO.

The default is <tt>'false'</tt>. |

<tt>SMTP_SERVER</tt>

The SMTP server to use to send errors over e-mail.

Only applicable when <tt>EMAIL_ERRORS</tt> is set to <tt>'true'</tt>.

The default value is an example that must be modified to be useful. |

<tt>EMAIL_TO</tt>

A comma separated list of e-mail address to set failure and warning notifications to.

Only applicable when <tt>EMAIL_ERRORS</tt> is set to <tt>'true'</tt>.

The default value is an example that must be modified to be useful. |

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. In a command prompt window change to the test directory:

*_cd

Unknown macro: {LEXEVS_HOME}

\test_*

Run the TestRunner utility to start the test process:

*_> TestRunner.

Unknown macro: {ext}

-h_*

where _

_ is the extension appropriate for your operating system (bat for Windows, sh for Unix)

For example:

Windows:

<tt>TestRunner.bat -h</tt>

Unix:

<tt>./TestRunner.sh -h</tt>

Note: The image shows the test partially in progress. | Unable to render embedded object: File (Test_Directory.jpg_) not found.

</html>

Content

Space Tools

Installing LexEVS 5.x Local Runtime

Introduction

Preliminary considerations

Downloading and installing the LexEVS Local Runtime

What's inside

Configuring the LexEVS Environment

MySQL properties

PostgreSQL properties

Server properties

Testing the LexEVS Local Runtime