Choral Installation and Administration

Installation

Hardware and Software requirements

Database

Oracle Database 19c: the SQL API will be available on this database.

A user with very high privileges (like SYSTEM) is required for installation.

Choral Server

Windows based or Linux based (CentOS, RedHat, Debian or Ubuntu) operating system x86_64 version. Java 11 runtime environment (from version 21.19 to version 23.1.0). Java 17 runtime environment (from version 23.5.0). The installer will be installed on this machine.

The Choral Server contains index data, so confidential data must be secured. Data is cached and most of the calculation is made on the Choral Server, so high amount of memory and high CPU speed with many cores is recommended.

Communication

The communication between the database and the Choral Server is via web services. The database calls the endpoints of the Choral Server on a configured port. Communication speed is a major factor at the performance of some queries.

Download

Download package for your operating system (tar.gz for Mac OS) from JChem Search Engines' download page.

Installation steps

Pre-installation steps needed in the case of an existing former Choral installation

1.a Stop the choral service sudo service choral stop 1.b Drop CHORAL_OWNER DROP USER CHORAL_OWNER cascade; 1.c Delete full content of /opt/chemaxon/choral/ (on linux) or C:\Program Files\Chemaxon\choral\ (on Windows)

Run of the installers

###### Linux Deb (e.g. Ubuntu)
sudo dpkg -i choral_linux_<version_number>.deb

###### Linux Rpm (e.g. CentOS, Fedora, RedHat)
sudo rpm -i choral_linux_<version_number>.rpmResult:installed Choral application under /opt/chemaxon/choral/

###### Windows
Run choral_windows-x64_<version_number>.exe as administrator.

###### Mac OS
gunzip choral_unix_<version_number>.tar.gz

`tar xvf choral_unix_<version_number>.tar`

Configure

Checking and entering the appropriate data into the configuration files are very important steps of the installation process. Two files serve for configuration:

Linux

/opt/chemaxon/choral/config/application.properties

/opt/chemaxon/choral/config/choral.conf

Windows

C:\Program Files\Chemaxon\choral\config\application.properties

C:\Program Files\Chemaxon\choral\config\choral.conf

Open a terminal window (as administrator in Windows) and go to the installation directory, which is /opt/chemaxon/choral in Linux, your selected installation directory in Windows and the directory where you have unzipped the tar.gz file in Mac OS.

application.properties

parameter	comment
choral.init.oracleUrl	The url of the database to connect must be set. The format is jdbc:oracle:thin:@<host>:<port:<sid>.
choral.init.hostname	By default, the hostname is detected and offered by the installer. If you want to specify another .
choral.init.grantingUser	Database user with System privileges .
choral.init.owner	If you want to have more Choral cartridges installed in the same database, different settings are required in each installation for the following properties. You can specify other callback user name (the default is choral_owner)
choral.init.indexerRole	A cartridge indexer role is created during installation. You can specify the indexer role as (the default is choral_indexer)
choral.init.searcherRole	A searcher and general cartridge user role is created during installation. You can specify the searcher role as (the default is choral_searcher)
choral.init.useJobs	You can specify if Choral cartridge should create and run jobs to improve data modification performance. The default is true, however, if you don't want to/can't give access rights to do so, you can change this setting to false with some performance loss. In case of true a create job privlege is required for the choral_owner.

Set up allocated memory in choral.conf file

Serves for further configurations, e.g. for tuning the performance of the search processes. Its modification is optional.

The full heap memory given to the server can be set in the choral-service.vmoptions and in the run-choral.vmoptions file, while its distribution can be set in the choral.conf file. A memory calculation page is available to generate optimal memory settings. Memory settings can be changed and be applied after restarting the service. The default Xmx value is determined by Java execution engine. For more information about the default Xmx value see How is the default max Java Heap size determined?.

CHORAL_SETTINGS table

After the installation is finished, the CHORAL_SETTINGS table of the callback user (by default CHORAL_OWNER) stores the HOST IP address and PORT number of the installed Choral server. Choral server’s host and port can be configured here.
Put the license file into /opt/chemaxon/choral/license/ folder and make the license file readable.

Choral Cartridge license is required, by default. The use of other standardizer actions than the default, or the use of some special chemical terms requires further licenses.
Set JAVA_HOME environmental variable or put a specific Java version into opt/chemaxon/choral/java/ folder. If left this is left empty, the Java specified in JAVA_HOME will be used.
Create molecule type files

Molecule types define the interpretation mode of the chemical structures. The definition of these types has to be stored in <choral_home>/data/types/ folder as a <molecule_type_name>.type file. The type files planned to use by the cartridge must be created before the Initialize step
Initialize the server

Before initializing the server always check the config/application.properties file.

Be sure the user name with System privileges is correct, the server host name, port, and choral callback user name are the intended ones.

Also set up the molecule types, because they can’t be changed later.

{warning} Initialization needs empty / data/store/ folder, consequently already existing index data cannot be preserved if server initialization must be repeated.

Re-indexing will be required.

Two methods can be followed in order to initialize the server by running the following command as superuser on Windows, choral user on Linux:
1. Initialization with SQL script execution
  
  Windows (in an administrator terminal):
  
  init-choral
  
  Linux:
  
  sudo -u choral ./init-choral
  
  Mac OS:
  
  ./init-choral
  
  When prompted for password, type the password of choral.init.grantingUser (the user with SYSTEM privileges). If you want to run it in silent mode, you can add the --password and your password as a parameter:
  
  ./init-choral --password <your_password>
  
  The password of choral.init.owner (the choral owner) is generated by the init-choral script to be the same as choral.init.owner itself. However, in some databases the local password rules require the passwords be composed of upper case, lower case letters, numbers and additional specific characters. If this is your case, run the init-choral script in the following form (available from version 21.13). Some special characters cannot be used this way.
  
  ./init-choral --password <your_password> --ownerPassword=<your_choral_owner_password>
  
  The generated password of the choral owner can be checked in <choral_home>/sql/1_createUser.sql file.
2. Initialization without SQL script execution
  
  Windows:
  
  init-choral-service
  
  Linux:
  
  sudo -u choral ./init-choral-service
  
  Mac OS:
  
  ./init-choral-service
  
  In case the second method is followed, the steps described in section Prepare Choral environment in Oracle must also be executed.
Run the server

run-choral.exe (on Windows)

run-choral.sh (on linux)

On linux if the deb or rpm installer was applied, the next initialization method is also applicable:
```
sudo service choral start
```
The stop | status switches also work.
Create system service

Optional.

on Windows, run as administrator: install_service.bat (name of the service is JChem Choral Cartridge, set up as any windows service from this step, can be uninstalled by uninstall_service.bat )

on linux: choral-service.sh (set it up according to your operating system. The deb and rpm installers will also do this step.)
Prepare Choral environment in Oracle

If the second initalization method was followed, run the sql files provided by the initialization

Run the following sql files present in sql folder in the following order:

As System
```
install_system.sql
```
or
```
1_createuser.sql
2_http.sql
```
As choral_owner

{warning} Prerequisite: the server is running
```
install_choral.sql
```
or
```
3_choral_settings.sql
4_logger.sql
5_indexType.sql
6_choral_idxstat.sql
7_choral_assoc_stats.sql
```
{warning} It is advised not to use the choral_owner schema for any other purpose than maintaining the cartridge (e.g. don’t store your business data in this schema).

Molecule type

Molecule types define the interpretation mode of the chemical structures. The definition of these types has to be stored in <choral_home>/data/types/ folder (Linux) or C:\Program Files\Chemaxon\choral\data\types\ (Windows) as a <molecule_type_name>.type file. Type file names cannot contain capital letters. You can add, modify, delete molecule type files according to your needs.

We provide a sample type, see file <choral_home>/data/types/sample.type (Linux) or C:\Program Files\Chemaxon\choral\data\types\sample.type (Windows).

The following settings can be defined in a <molecule_type_name>.type file:

Version of the type descriptor (at the moment, only '1' is accepted)
Type ID: positive unique identifier among types
Tautomer mode: OFF, GENERIC, CANONIC_GENERIC_HYBRID (or) NORMAL_CANONIC_GENERIC_HYBRID, NORMAL_CANONIC_NORMAL_GENERIC_HYBRID

CANONIC_GENERIC_HYBRID is available from version 20.12 and is deprecated in version 23.12
NORMAL_CANONIC_GENERIC_HYBRID available from version 23.12 with the same fuctionality as CANONIC_GENERIC_HYBRID
NORMAL_CANONIC_NORMAL_GENERIC_HYBRID available from version 23.12
canonicalTautomerHeavyAtomLimit: default value 100, available from version 22.21
stereoAssumption: ABSOLUTE, RELATIVE (Available from version 20.12.)

This parameter affects the tetrahedral stereo interpretation mode of structures without chiral flag. See table here. The upper row represents ABSOLUTE, the lower row represents RELATIVE.
Standardizer action string or Standardizer file containing standardization requirements

Standardizer action string must follow the syntax of command line standardizer actions:

Example :

`standardizerAction = aromatize:b..addexplicitH..replaceatoms:queryatom='N':replaceatom='O'`

Standardizer configuration file can be created as described in Creating a Configuration Standardizer page.

Example :

`standardizerFile = <choral_home>/data/types/customStandardizerConfiguration.xml`

{primary} The types stored in <choral_home>/data/types/ are loaded when the choral service is initialized. Therefore, if you add a new molecule type or change an existing one, the following steps have to be executed:

Create/modify/delete molecule type file(s) according to needs

Stop the service choral

Delete the content of the index directory: <choral_home>/data/store/ (Linux) or C:\Program Files\Chemaxon\choral\data\store\ (Windows)

Initialize the service choral

Start the service choral

The chemical domain indexes (<type>_indextype) must be newly created

Administration

Create users as System

Further users can be created, like table owner users, searcher users.


CREATE USER TABLE_OWNER IDENTIFIED BY <PASSWORD>;
GRANT CONNECT TO TABLE_OWNER;
GRANT RESOURCE TO TABLE_OWNER;
GRANT UNLIMITED TABLESPACE TO TABLE_OWNER;

CREATE USER SEARCHER IDENTIFIED BY <PASSWORD>;
GRANT CONNECT TO SEARCHER;
GRANT RESOURCE TO SEARCHER;

Grant privileges as choral_owner

Grant the necessary privileges to TABLE_OWNER and SEARCH users through ROLES (specified in the application.properties file).


GRANT CHORAL_INDEXER TO TABLE_OWNER;
GRANT CHORAL_SEARCHER TO SEARCHER;

If the privileges are not granted through the above roles, the execute rights can also be granted one-by-one to the appropriate users. The following grants must be separately repeated for each molecule type present in /data/types/ folder when the service was initialized.

Execute privileges must be granted to table owners for creating <type>_idxtype domain indexes.


GRANT EXECUTE ON sample_idxtype TO TABLE_OWNER;

Execute privileges must be granted to table owners and searcher users for using the <type>_search and <type>_relevance operators (that is privileges for searching).


GRANT EXECUTE ON sample_search TO TABLE_OWNER;
GRANT EXECUTE ON sample_relevance TO TABLE_OWNER;
GRANT EXECUTE ON sample_search TO SEARCHER;
GRANT EXECUTE ON sample_relevance TO SEARCHER;

Further execute privileges can added optionally to the appropriate user:


GRANT EXECUTE ON isValidMolecule TO TABLE_OWNER;
GRANT EXECUTE ON chemterm TO TABLE_OWNER;
GRANT EXECUTE ON molconvert TO TABLE_OWNER

Grant select privileges as table_owner

As table owner, you must give select privileges on your table(s) to searcher users.


GRANT SELECT ON <tablename> TO SEARCHER

Using synonyms

There are no known restrictions using synonyms. Granting privileges is still required according to the Oracle privilege handling logic.

Here are some examples:


CREATE OR REPLACE SYNONYM TABLE_OWNER.sample_idxtype for <choral_owner>.sample_idxtype;
CREATE OR REPLACE SYNONYM SEARCHER.sample_search for <choral_owner>.sample_search;
CREATE OR REPLACE SYNONYM SEARCHER.sample_relevance for <choral_owner>.sample_relevance;

In the case of these examples you can simplify your SQL statements by doing the following:

You can replace "<choral_owner>.sample_idxtype" with "sample_idxtype" when logged in as TABLE_OWNER.

You can replace "<choral_owner>.sample_search" and "<choral_owner>.sample_relevance" with "sample_search" and "sample_relevance" respectively when logged in as SEARCHER.

Health check query

After replacing coral_owner with your installed choral owner's name, the following query will check whether the system is working fine:


SELECT * FROM DUAL WHERE <choral_owner>.sample_search('CCC', 'CCC', 'SUBSTRUCTURE')=1

The query must return 1 row.

Change the Choral Server machine or directory, IP address or port

Stop using the Cartridge.
Stop the Choral Server
In case of changing the machine/directory :

Copy the configuration folder (i.e. /opt/chemaxon/choral) on the Choral Server to the new machine/directory. Don’t forget to copy the store directory containing index data and user types if their location were reconfigured.
In case of changing the port :

Change the server.port property in the application.properties file
Start the Choral Server on the new machine/directory.
In case of changing the machine/IP address :

Check the IP of the (new) Choral Server which the database can connect to. A simple way to do it is to log in to the database from the new machine and call:
```
SELECT SYS_CONTEXT ('userenv','ip_address') FROM DUAL;
```
In case of changing the machine/IP address :

log in as choral_owner to the database and run the following script:
```
UPDATE CHORAL_SETTINGS SET value='<host>' WHERE NAME='HOST';
COMMIT;
```
In case of changing the port :

Log in as choral_owner to the database and run the following script:
```
UPDATE CHORAL_SETTINGS SET value='<port>' WHERE NAME='PORT';
COMMIT;
```
In case of changing the machine/IP address and/or the port :

Modify the values of host, lower_port, upper_port accordingly in the file /sql/2_http.sql and run 2_http.sql as SYSTEM user.
The cartridge is ready to use. Start using the cartridge again.

Changing setting of using jobs

choral.init.useJobs This setting can be changed later by doing the following:

Change from true to false:

Change the following setting as CHORAL_OWNER.


UPDATE CHORAL_SETTINGS SET value='1' WHERE NAME='PARALLEL_BATCH_COUNT';
COMMIT;

You can also revoke the grant to create jobs from the CHORAL_OWNER.

Change from false to true:

The create job privilege must be given to the CHORAL_OWNER (if it was missing)


grant create job to CHORAL_OWNER;

The parallel batch count parameter must be set to greater than one (10 is the default at installation).


UPDATE CHORAL_SETTINGS SET value='10' WHERE NAME='PARALLEL_BATCH_COUNT';
COMMIT;

To allow the index creation to run in parallel batches it is necassary that the value of the database parameter JOB_QUEUE_PROCESSES is greater than 1.

Logging configuration

Logging of the Oracle side of Choral cartridge is described here.

Logging outputs

table CHORAL_LOG
standard Oracle dbms_output

Available logging levels

OFF
ERROR
WARN
INFO
DEBUG

Examples


exec logger.set_table_level('ERROR'); 
exec logger.set_dbms_output_level('WARN');

Logging level can be overridden for the current session as well.

Examples


exec logger.set_table_session_level('OFF');
exec logger.set_dbms_output_session_level('DEBUG')

Default settings

TABLE level: INFO

DBMS_OUTPUT level: ERROR

Update

From version 22.16.0, a new upgrade method - requiring no downtime - is also provided. See documentation.

During the update, the new version of JChem Choral has to be installed on the old version. Re-indexing of the structure columns will be required.

The steps to be executed are similar to the installation steps of a new JChem Choral, but there are differences, see here:

Step 1 : only execute 1a and 1c

Step 2: install the new version of JChem Choral

Step 3-6: no need to execute

Step 7: optional; new molecule type files can be added or the already present ones can be modified, deleted

Step 8: Update the server instead of Initialize the server

{warning} Update needs empty / data/store/ folder, consequently already existing index data cannot be preserved if server update must be repeated. Re-indexing will be required.

run update-choral instead of init-choral

Step 9-11: no need to execute

The <type>_idxtype indexes on structure columns should be dropped and created again. Before dropping the indexes, their CREATE INDEX DDL statements should be saved for using them when the indexes are created again.

DROP INDEX <index_name>;
CREATE INDEX <index_name> ON <table_name>(<structure_column_name>) INDEXTYPE IS <type>_idxtype;

Uninstallation

Database

Drop the choral owner.

Choral Server

Uninstall the created service or remove the extracted folder created at the install. Remove the data and logs folders if they were configured.