Plexus Connect - Installation and System Requirements

    On this page:

    Hardware and software requirement

    Plexus Connect is a web-based application with the following software requirements:

    On the server side:

    {primary} From version 23.11. Tomcat 10 or Jetty 9 are required

    • Any database compatible with Instant JChem ( i.e. , Oracle, MySQL, Microsoft SQL, Derby, PostgreSQL);

    • Web server: Jetty 8, Apache Tomcat (versions 8 and 9). Please note that this requirement is optional because the application is bundled with Jetty;

    • Starting with version 23.11.0, Plexus Connect requires either Tomcat 10 or Jetty 9 to run.

    • Minimum memory required: 4 GB.

      Supported major Java versions:

      {primary} From version 23.11.0 Java 17 is required)

      • Adoptium 11 (from IJC version 20.11.0 supported, from IJC version 21.20.0 is an option instead Oracle Java)
      • Java 11 (from IJC version 20.11.0 supported, from IJC version 21.20.0 JRE for Java 11 required)
      • Adoptium 8 (from IJC version 18.22.0 and LTS Carbon 1 until IJC version 21.14.0 and LTS Helium)
      • Java 8 (from IJC version 15.2.20 until IJC version 21.14.0 and LTS Helium)

    On the client side:

    • JavaScript enabled web browser. The currently supported browsers are: Google Chrome, Mozilla Firefox, Microsoft Edge and Safari.

    {primary} Internet Explorer is not supported by Plexus Connect.

    For administrators:

    • The same version of the Instant JChem desktop application as an administrator tool (managing user accounts and the relational database, creating form and grid views...).

    Operating system

    There is no restriction on the operating system, you can use it on:

    • Windows

    • GNU/Linux

    • Mac OS X

    License requirement

    A valid license file containing Plexus Connect and Instant JChem Enterprise licenses has to be placed in the ${HOME}/.chemaxon/licenses/ (in Unix systems) or in the %USERPROFILE%\chemaxon\licenses\ (in Windows systems) folder, where ${HOME} (or %USERPROFILE%) means the home directory of the user running the web server.

    The Plexus Connect license covers the basic functionality of Plexus Connect (opening forms and table, running queries, list management...).

    Marvin JS, the default chemical editor integrated into Plexus Connect requires a Marvin JS license, which needs to be added to the same folder in a separate license file.

    Please consult our sales team (sales@chemaxon.com) if you would like to require a license for Plexus Connect or if you need help in handling your license file.

    Preparing for Installation

    Download Plexus Connect

    Plexus Connect is available as a single .war file. In order to download the installation package, please navigate to the download page of Plexus Connect on the Chemaxon website. Before you can download the file, you will be asked to log in with your Chemaxon username and password.

    Configuration

    In order to access your databases through Plexus Connect, you will need to configure an Instant JChem schema for each database connection before the server part of the application is started. If Plexus Connect does not have an existing schema, you can create one in the Instant JChem desktop application (IJC) and then configure it for use with Plexus Connect.

    Preparing an Instant JChem project
    1. Create a new project or open an existing one in IJC. You can choose from an empty project, a project with an existing database or a project with already imported demo data.

    2. Set up the desired security configuration for the project. Please note that a project with the Default (anonymous) security policy cannot be used in Plexus Connect.

      A detailed description can be found here in the relevant part of the Instant JChem user documentation.

    3. Create the necessary user accounts and assign the appropriate user roles to them. The details for managing user accounts can be found in the Instant JChem User Guide.

    4. Add your chemical data to the project and design any database views (tables and forms) you will need for browsing the data in Plexus. Make sure that these database views are accessible for every user with the appropriate user role. A more detailed description about sharing database items is available here.

    5. Connect to the schema as administrator and in the Schema Settings dialog select the Remember username and Remember password options.

    6. Disconnect the schema.

    7. Close the IJC project.

    Configuring a database connection

    A database connection is described in a schema configuration ( .ijs ) file. In order to connect to a database from Plexus Connect, each .ijs file has to be put

    • either in its default location, in the ${HOME}/.chemaxon/plexus-suite folder in UNIX systems (or in the %USERPROFILE%\chemaxon\plexus-suite\ folder in a Windows system);

    • or in a location specified in the ijc.schemas.dir property of the nps.properties file.

    {success} Please note that the .ijs file for an already existing Instant JChem project can be found in the .config folder of the Instant JChem project directory.

    Even if using a Derby database, the .ijs file must contain the URL to the database. This information can be found in the Instant JChem desktop application: in the Projects window right-click on the schema's node and select Schema settings.

    For a detailed description, please, check the Instant JChem user documentation here.

    The schema configuration file has to contain the ijc.username and ijc.password properties (as well as the database.username and database.password properties if necessary). In addition, the ijc username and password has to belong to a user account which has administrator role assigned to it in Instant JChem.

    User accounts

    {warning} Please be aware that the admin user specified in the .ijs configuration file has to be kept solely for the internal operations of the Plexus Connect server and it cannot be used as a "standard user". It is recommended to change the admin account username to be easily distinguished, for example to connect_service_account. Logging in with this user account either into Plexus Connect or into Instant JChem has to be avoided since it can cause problems in the behavior of the backend part of Connect. You should use different user accounts for connecting to your database with the Plexus web application and with the Instant JChem desktop application. Starting the Plexus server with user "A" defined in the .ijs file and later connecting to the database with the same user from Instant JChem results in the server producing runtime errors.

    As there are differences between use cases of Plexus Connect, it is useful to apply some connection pool settings in schema configuration. These settings have to be saved for each schema in its respective .ijs file and the same properties as for Instant JChem are available. Please note that the default settings for maximum active connection is set to 6, which might become a performance limitation for organisations with high number of concurrent users who have to share the defined number of connections.

    Every deployed schema should have the same security setting because the user login details are used for every schema in the Plexus directory. Since 15.12.7.0 version the server attempts to authenticate the user against the first schema and in case it fails, no other attempts are made. This behavior can be changed in the nps.properties file using the multiple.schemas.auth property. Setting this property to true leads to the user login details being used for authentication in all schemas available .

    Custom configuration

    Since 19.23.0 version, the nps.propertiesconfiguration file is automatically created during application start with default content in the working directory (${HOME}/.chemaxon/plexus-suite in UNIX or in the %USERPROFILE%\chemaxon\plexus-suite in Windows). The nps.properties file contains a number of configuration properties. Detailed instructions how to customize the nps.properties file can be found on the Configuration Files documentation page here.

    Maximizing the number of simultaneous queries

    Another property can be added to the schema configuration ( .ijs ) file to set the maximum number of queries which can run simultaneously on the server side. The default value is five simultaneous queries. You change this value by adding the following line to your .ijs file (replace the text in italics with the actual number of parallel queries enabled):

    <entry key = "server.max.queries">maximum number of simultaneously running queries</entry>

    When the number of parallel queries exceeds this value, the subsequent queries will be waiting in a queue on the server side.

    Running Plexus Connect

    The downloaded executable .war file can be deployed to a servlet container or it can run standalone.

    Deploy the web application

    The downloaded .war file has to be deployed into a web server with a servlet container. For the exact deployment steps please consult the documentation of your chosen servlet container, for example, Eclipse Jetty or Apache Tomcat. Use HTTPS in order to safely access your database without sending passwords unencrypted.

    The Plexus Connect application is working and tested with https protocol.

    If reverse proxy is used with SSL configuration, please make sure these headers are forwarded properly:

    X-Forwarded-PortX-Forwarded-Proto

    The bundled, embedded Jetty is already configured for accepting these.

    In the case of Tomcat, RemoteIpValve configuration is required.

    Running Plexus Connect standalone

    If you want to run Plexus Connect in a standalone mode, you have to use the single executable .war file in the following way:

    • The downloaded executable .war file (plexus-suite-XXX.war) contains the whole application. The basic approach to launch it is:

    java -jar plexus-suite-XXX.war

    • The command above will create a new "webapp" folder in the system's temporary folder containing the application. To change the location of this directory, the tempDir system property has to be passed to the java command:

    java -DtempDir=/some/custom/path/connect-webapp-exe -jar plexus-suite-XXX.war

    • By default, the application runs on port 8080. To change this, the port system property might be passed to the java command:

    java -DtempDir=/some/custom/path/connect-webapp-exe -Dport=9000 -jar plexus-suite-XXX.war

    Docker image for Plexus Connect

    How to download the docker image in particular version:

    • Go to https://download.chemaxon.com/plexus-connect.

      • For the frequent release, stay on the page and select option CLI with Docker
      • For the LTS releases, go to LTS release page and select option CLI with Docker
    • Use the commands from the first section to login to Docker

      • It looks like this:
      • echo someapikeygeneratedforyou | \ docker login -u yousername@chemaxon.com --password-stdin hub.chemaxon.com
    • download the image you want, see the other command section on website, use version number as image tag

      • e.g. for Lithium 1 the command for download would be docker pull hub.chemaxon.com/cxn-docker-release/connect-public:22.17.1
      • e.g. for frequent the command for download could be docker pull hub.chemaxon.com/cxn-docker-release/connect-public:22.19.3

    How to prepare and use docker image:

    • prepare your Chemaxon folder, so it contains the license and IJC project like for normal Plexus Connect installation

    • Run docker and configure volume, so your ~/chemaxon folder is visible inside Docker container

      • Volume always has to point to /home/connect/.chemaxon
      • Typical command to start the docker container would be docker run -d -p 8080:8080 -v pathToChemaxonFolder:/home/connect/.chemaxon --name desiredNameOfYourContainer hub.chemaxon.com/cxn-docker-release/connect-public:<VERSION_TAG>

    Docker image for Python Scripting API

    Using Python scripting API in Plexus Connect inside supplied docker container provided by Chemaxon.

    ​ To use Python installed in a Docker container with libraries installed on the host machine, you can mount the host machine's directory containing the libraries as a volume in the Docker container.

    ​ Technically it means adding another volume parameter to Connect docker container.
    When you use command docker run for creating Connect docker container, add another -v flag:

    • -v "<HOST_DIR_WITH_PYTHON_LIBS_INLUCING_CONNECT_API>:/opt/pythonlibs"
    • HOST_DIR_WITH_PYTHON_LIBS_INLUCING_CONNECT_API should be the absolute path leading somewhere to libs in your Python installation on the host system.

    ​ Now the Python installed inside the Docker container will try to find additional libs in the directory you mounted to container.

    Make sure you install all the Python libs you need for your Python scripts on your host machine.

    ​ Chemaxon configuration folder will be mapped as it is described above in Docker image for Plexus Connect section.

    Because Python executable inside Connect docker is named python3, you have set some value in nps.properties (inside your mounted CHEMAXON_FOLDER/nps.properties).

    • add/uncomment/replace there the scripting.pythonBin parameter with value python3.

    ​ You can now use Python scripts invoked by Connect just as you would use it when running Connect directly without Docker. ​

    Note/warning

    Scope of this section only applies when calling Connect from external Python scripts, but theoretically outcome of this is valid for all external access to Connect in our Docker image.

    ​ You can also run Python scripts, directly or e.g. with Jupyter notebook with your host machine Python installation against Connect running inside the Docker container, however there are some caveats:

    • Connect Python API is designed to call Connect via HTTP protocol, but using some reverse proxy or other network infrastructure to enable HTTPS communication is needed for successful connection here, otherwise Python calls to Connect will fail.
    • Technically the networks inside the container and outside the Docker container are different, so some critically important Cookies would be lost during transfer.
    • Long story short, when calling Connect address inside your external Python scripts, make sure Connect is reachable on https:// address from the Python script.

    Configuring Server Logging

    The sever side of Plexus Connect uses Logback as a logging framework. By default, the server is configured with the logback.groovy file bundled with the application and it logs messages into the logs directory located in the same directory from which the server has been started.

    To change the logging configuration, the logback.configurationFile switch can be used to provide a customized Logback configuration file. Instead of creating your own configuration file from scratch, the one bundled with the application might be used as well. It can be found in:

    • plexus-suite-<version>.war/WEB-INF/classes/logback.groovy in the case of the executable WAR file, or in

    • WEB-INF/classes/logback.groovy in the case of the deployed application.

    For customization, follow these steps:

    1. Locate and copy-paste the bundled logback.groovy file, e.g. , to $HOME/ps-logback-custom.groovy;

    2. Tweak it to your need. For example, in line logger("jdbc.sqltiming", OFF), change OFF to INFO to turn on SQL logging;

    3. Start the server using the logback.configurationFile parameter: java -Dlogback.configurationFile=$HOME/ps-logback-custom.groovy -jar plexus-suite-<version>.war;

    • Be sure to specify the logback.configurationFile before -jar...;

    • Be sure to use the absolute path for the Logback file, and not the relative one.

    Getting the log files for the Plexus backend and frontend

    Admin users can download the log files for the Plexus backend and frontend, respectively from the User account > About > Log files ).

    images/download/attachments/13109384/Connect.png

    In order to help administrators in finding the log files, the location of log file directory is included in the standard output of the Plexus backend. This means that the information about where to find the log files is printed

    • to the console when the executable WAR file is used;

    • into the catalina.out file in the case of Tomcat (and similarly for other application containers).