Choral Installation and Administration

    Installation

    Hardware and Software requirements

    Database

    Oracle Database 12c release 2 or later: the SQL API will be available on this database.

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

    JChem Server

    Windows based or Linux based (CentOS, RedHat, Debian or Ubuntu) operating system x86_64 version. Java 8 runtime environment. The installer will be installed on this machine.

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

    Communication

    The communication between the database and the JChem Server is via web services. The database calls the endpoints of the JChem 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.

    Install

    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>.rpm

    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

    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.

    The installation directory contains the following folders:

    Config folder

    Stores the following files

      • Application.properties

    The url of the database to connect must be set. The format is jdbc:oracle:thin:@<host>:<port:<sid> and can be set as:

    choral.init.oracleUrl=

    By default the hostname is detected and offered by the installer. If you want to specify another, enter it as

    choral.init.hostname=

    User with System privileges can be specified as

    choral.init.grantingUser=

    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.owner=

    A cartridge indexer role is created during installation. You can specify the indexer role as (the default is choral_indexer)

    choral.init.indexerRole=

    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.searcherRole=

    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.

    choral.init.useJobs=

    • choral.conf

    Serves for further configurations, e.g. for tuning the performance of the search processes. Its modification is optional. Optimal memory settings can be set by using the memory calculator page.

    CHORAL_SETTINGS table

    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.

    Data folder

    • store : stores the index data, by default

    • types : stores the molecule type files, by default

    See some general information about the molecule types

    Java folder

    You can put a specific Java version into this folder. If left empty, the Java specified in JAVA_HOME environmental variable will be used.

    Lib folder

    Contains choral-backend-server.jar file. Do not modify it.

    License folder

    Place here your license file, named as license.cxl . Otherwise, the license file present under your home/chemaxon/ will be used.

    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.

    Logs folder

    Log files relating to the choral service are saved here, by default.

    Sql folder

    SQL files generated by running init-choral.exe or init-choral.sh are placed here. Do not modify them.

    Set up allocated memory

    The full heap memory given to the server can be set in the choral-service.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.

    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:

    Initialization with SQL script execution

    Windows:

    init-choral in an administrator terminal.

    Linux:

    sudo -u choral ./init-choral

    Mac OS:

    ./init-choral

    When prompted for password, type the password.

    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.

    choral-service.exe --install (on Windows, run as administrator, set up as any windows service from this step)

    choral-service.sh (on linux, 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).

    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 execute privileges as choral_owner

    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 to searcher users.

    
    GRANT SELECT ON <tablename> TO 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 JChem Server machine or directory, IP address or port

    1. Stop using the Cartridge.

    2. Stop the JChem Server

    3. In case of changing the machine/directory :

      Copy the configuration folder (i.e. /opt/chemaxon/choral) on the JChem 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.

    4. In case of changing the port :

      Change the server.port property in the application.properties file

    5. Start the JChem Server on the new machine/directory.

    6. In case of changing the machine/IP address :

      Check the IP of the (new) JChem 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;
    7. 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;
    8. 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;
    9. 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.

    10. 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;

    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

    Uninstallation

    Database

    Drop the choral owner.

    JChem Server

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