Page History
Scrollbar | ||
---|---|---|
|
Page info | ||||
---|---|---|---|---|
|
Panel | ||||
---|---|---|---|---|
| ||||
|
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
Warning | ||
---|---|---|
| ||
LexEVS has been tested with the operating systems and hardware specified in the LexEVS 5.x 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 LexEVS 5.x 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 WIP LINKS 6 - Installing LexEVS 5.x and Higher Local Runtime (optional Optional Command Line Method) if you should choose this route.
- Complete the Downloading #Downloading and installing 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
|
| |||||||||||
2. Using a file explorer, navigate to the
Then enter the command to begin the installation wizard:
...where
|
| |||||||||||
3. Click the OK button to begin the installation.
|
| |||||||||||
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
Click the Next button.
|
| |||||||||||
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. |
| |||||||||||
8. Once all the components have been installed, a Finished dialog box will be displayed. Click Next. |
| |||||||||||
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 Downloading #Downloading and installing Installing the LexEVS Local Runtime. |
|
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 contentContent | |||||
---|---|---|---|---|---|---|
/admin | 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. | |||||
/doc | Optionally installed. This directory provides documentation related to LexEVS services, configuration, and execution. This guide is distributed in the /doc top-level directory. | |||||
/doc/javadoc | 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 | |||||
/examples | Optionally installed. This directory provides a small number of example programs. | |||||
/examples/resources | Contains sample vocabulary content for reference by the example programs; use the /examples/LoadSampleData command-line script to load for example code use or use one of the loaders in the /admin folder to load other content. | |||||
/gui | 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. | |||||
/logs | Default location for log files, which can be modified by the | |||||
/resources | 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. | |||||
/runtime | 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._
| |||||
/runtime/sqldrivers | The JDBC drivers used to connect to database repositories are not included in the lbRuntime.jar. Instead, the runtime scans this directory for the drivers to include. This can be overridden by path settings in the lbconfig.props file.
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 lbconfig.props 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. | |||||
/runtime-components | Optionally installed. Due to license considerations for additional materials (as described by the license.pdf and license.txt files in the install directory), the cumulative runtime provided in the lbRuntime.jar is not redistributable.
| |||||
/runtime- | This subdirectory includes all 3rd party code redistributed with the LexEVS runtime, along with respective license agreements. | |||||
/source | Optionally installed. This directory provides central accessibility to Java source for all code developed for the LexEVS project. | |||||
/test | Optionally installed. This directory provides an automated test bucket that can be used by System Administrators to verify node installation. Note that the /runtime/config/lbconfig.props file must still be configured for database access prior to invoking the test bucket. | |||||
/uninstaller | 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 LexEVS 5.x Prerequisite Software Supported. 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.
...
Info | ||
---|---|---|
| ||
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. |
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 {MYSQL_HOME}/my.ini.
...
...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 following file contains properties controlling the behavior of the PostgreSQL database server:
...
Property Name | Description |
---|---|
shared_buffers | Number of shared buffers. |
work_mem | The amount of memory in kilobytes allocated to working memory |
maintenance_work_mem | The amount of memory in kilobytes allocated to maintenance working memory. |
enable_seqscan | We set the ' |
Server Properties
The next step is to configure LexEVS. This is wrapped up in editing one file, {LEXEVS_HOME}/resources/config/lbconfig.props.
This file contains properties controlling the behavior of the LexEVS Local Runtime.
...
Property Name | Description | ||
---|---|---|---|
DB_URL | Required: The address of your database server. This will include the host name or IP address followed by the name of the database that you created to store LexEVS data. For example:
...where | ||
DB_PREFIX | Required for Oracle databases: The prefix to use on all tables or databases that LexEVS creates. | ||
DB_PARAM | Optional variable for passing extra database parameters. These will be appended to the end of the database connection string. | ||
DB_DRIVER | Required: The Java class name that represents the driver that you wish to use with your database. | ||
DB_USER | Required: The database username. This account must have permission to add and remove tables, indexes, etc inside of this database. | ||
DB_PASSWORD | Required: The password for the database username. | ||
LG_CONFIG_FILE | 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. | ||
LG_BASE_PATH | This variable is the path that will be used to resolve any other relative (or unqualified) paths in the lbconfig.props file. | ||
JAR_FILE_LOCATION | The path of the folder that contains your SQL drivers and LexEVS extensions (if you have any). | ||
REGISTRY_FILE | The location of the file that will store information about all loaded terminologies. | ||
INDEX_LOCATION | The folder where all LexEVS generated indexes will be stored. This folder can potentially be large (100+ GB) - depending on the terminologies loaded. | ||
MAX_CONNECTIONS_PER_DB | 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) | ||
CACHE_SIZE | 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. | ||
ITERATOR_IDLE_TIME | 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. | ||
MAX_RESULT_SIZE | This controls the maximum number of results that a user can resolve at one time for the CodedNodeSets and CodedNodeGraphs. | ||
LUCENE_MAX_CLAUSE_COUNT | 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. | ||
LOG_FILE_LOCATION | The path where LexEVS log files will be written. | ||
API_LOG_ENABLED | Setting API call logging to 'true' will cause every method call to be printed to the log file. | ||
SQL_LOG_ENABLED | Setting SQL logging to 'true' will cause every sql statement executed to be printed to the log file. | ||
DEBUG_ENABLE | Setting debug to 'true' will give you more verbose logging information to debug problems. This should normally be set to 'false' since debug logging causes a negative performance impact. | ||
LOG_CHANGE | Indicates when a new log file should be started. This can be set to 'monthly', 'weekly' or 'daily'. | ||
ERASE_LOGS_AFTER | If | ||
EMAIL_ERRORS | Used to enable or disable e-mail notification of system errors and warnings. If you set this to 'true', you must set | ||
SMTP_SERVER | The SMTP server to use to send errors over e-mail. | ||
EMAIL_TO | A comma separated list of e-mail address to set failure and warning notifications to. |
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:
...where
| !Test_Directory.jpg_! | |||||||
2. Use a file explorer to navigate into the directory that contains the test report. The report directory is placed in |
| |||||||
3. Launch the report into the default browser by double-clicking on the |
| |||||||
4. Review the test results. You should expect no failures or errors if the configuration of the Local Runtime and the databases is correct. If there are errors refer to the troubleshooting section. |
|
If all the tests pass then you have successfully installed the LexEVS Local Runtime. Congratulations!
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 in the databases, indexes, and lock files. They could be left in a state that will cause subsequent loads of the same terminology to fail.
- Often these can be remedied by deleting the lock.xml file followed by using the cleanup function.
- 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
andmetadata.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 a large number of connections. If LexEVS is configured for multi-database loads and has multiple users connecting to all terminologies, then the administrator will need to scale database configurations to adapt to this. If you have a large number of terminologies loaded and a large user base connecting to the service using the lbGUI, then you will need the database configuration for number of connections scaled appropriately or users may not be able to connect.
Info title Note Loading in single database mode can eliminate this problem.
- 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 CLI 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 following 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.Code Block {LEXEVS_HOME}/runtime/sqlDrivers/
- The latest version of Connector/J is available from MySQL.org. The new jar should be placed in the following directory:
- 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.
Scrollbar | ||
---|---|---|
|