Instant JChem Installation and Upgrade

    Installation

    Instant JChem can now be installed in three different ways:

    1. Traditional installer

    Download Instant JChem installer. Before installing a new Instant JChem version, ensure to uninstall any previous version.

    {primary} Starting with version 19.22.0, Instant JChem for Windows can now be installed using an MSI file. An MSI file is a type of installer package specifically for Windows, used to install a program, like Instant JChem, onto the system. This method allows for precise management of the installation process. Using the MSI file for installation is particularly useful for system administrators who need to install Instant JChem across a corporate network. It's important to note that the MSI package does not include Java, which must be obtained separately.

    After installing, remember to check for and load any available updates by going to "Tools" and then selecting "Plugins".

    2. Docker image for Instant JChem

    To download the docker image for particular version navigate to download page.

    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 with the following command:
docker pull hub.chemaxon.com/cxn-docker-release/ijc-jws-server:<version number>

    wherein, for example:

    • for frequent release replace <version number> with version number of interest, etc. 22.19.0
    • accordingly, for lts release replace <version number> with etc. lts-21.15.7

    Running IJC using Docker

    Default
    docker run -it --rm -p 8080:8080 jws-webappurl

    The app will be accessible at http://localhost:8080/UrlWebApp/.

    Sharing a project

    Add the zip file and ijp file to a local folder (example C:\Others\docker-jws-data\shared_projects) and bind it to the container on /usr/local/ijc_shared_data . The content of the folder will be copied to the right location inside the image.

    Lets assume I have myproject.zip and myproject.ijp inside shared_projects.

    docker run -it --rm -p 8080:8080 -v C:\Others\docker-jws-data\shared_projects:/usr/local/ijc_shared_data jws-webappurl

    The project can be accessed by this url: http://localhost:8080/UrlWebApp/prj.jnlp?startJnlp

    Of course, it might be helpful to also update the index.html file and add a reference to the new project. The updated index.html should also be placed in the same shared_projects folder.

    Proxy to server URL: http://www.YourWeb.com:9080/urldemo/
    docker run -it --rm -p 8080:8080 -e PROXY_WEB_SERVER="http://www.YourWeb.com:9080/urldemo/"  jws-webappurl

    The app will be accessible at http://localhost:8080/UrlWebApp/ but the links to projects and IJC will point to the chemaxon demo at http://www.YourWeb.com:9080/urldemo/.

    Different port
    docker run -it --rm -p 8888:8080 jws-webappurl

    The app will be accessible at http://localhost:8888/UrlWebApp/.

    Upgrade IJC

    you will need to provide a new index.html a new InstanJchem zip and a new info.properties. Put them all in a local folder, for example :\Others\docker-jws-data\shared_projects. The license file can also be put here.

     -v C:\Others\docker-jws-data\shared_projects:/usr/local/ijc_shared_jws
    Available configuration through environment vars (-e option)
    • CODEBASE
    • EXTRA_ARGUMENTS
    • LICENSE
    • PROXY_WEB_SERVER

    Folders to bind:

    • /usr/local/ijc_shared_data - add here things related to application data: shared projects, html pages
    • /usr/local/ijc_shared_jws - add here things related to IJC configuration: ijc zip file, info.properties, master.jnlp

    3. Java Web Start

    Since version 2.2 Instant JChem can be launched using Java Web Start (JWS). This allows you to load it directly from a web-page rather than needing to install it first. The Java Web Start version should be fine for most users, but it is slightly less flexible, for instance should you wish to install your own or a third party's extension. For more information about the Java Web Start look here.

    Auto-update

    {warning} Automatic Update Center functionality was removed from Instant JChem after version 18.8.0 and is no longer supported.

    About upgrading

    When upgrading Instant JChem using any method, there may be substantial updates to the JChem version or changes in the way your project information is organized. Although we strive to ensure that these upgrades are seamless and straightforward, it's important to be cautious if your projects contain critical information that can't be easily recreated. We strongly recommend backing up your data before proceeding with the update. To do this, you can choose one or more of the following options:

    • Export your data to a file (e.g. SD file).

    • Take a copy of the complete project. Create a copy or a zip archive of the complete directory containing your project(s). Note: this will only back up data in local databases.

    • If you are using a MySQL or Oracle database you should ensure that you have a database backup before you update. Backing up the IJC project directory will not backup the data in these databases.

    Upgrading Schema

    When a schema is connected in an IJC version that is newer than the version in which the project was created, a dialog box, as shown below, might appear, indicating that schema upgrade is required. This process occurs automatically and updates the IJC metadata to align with the current IJC version. It is important to note that the upgrade is irreversible. Once the schema has been updated, older versions of IJC will no longer be compatible with it. Therefore, the Schema upgrade dialog is set to No by default to prevent accidental upgrades. To upgrade the schema, choose the Yes, upgrade JChem tables (irreversible) option and click Upgrade IJC Schema. The duration of the process depends on the complexity of the schema, including the number of entities, relationships, etc.

    images/download/attachments/1803013/IJCschema1.png

    Upgrading JChem Tables

    The second upgrade that might be necessary when opening a schema in a new IJC version is the upgrade of JChem Tables. This upgrade is more frequent than the schema upgrade and is essential for ensuring that functions like search and calculations work properly in the new IJC version. By default, the upgrade is set to No to prevent unwanted changes. To perform the upgrade, select the Yes, upgrade JChem tables (irreversible) option and click Upgrade IJC Schema. The duration of this process depends on the number of JChem Tables that need to be upgraded.

    images/download/attachments/1803013/JChemtables1.png

    Installation problems?

    If you are having troubles installing or running IJC then the following notes might help.

    Userdir

    IJC saves various settings and all updates it gets from the Update Center in a "userdir" which is usually found in:

    • Windows - c:\Users\<username>\AppData\Roaming\.instantjchem\<version number>

    • Mac OS X - $HOME/Library/Application Support/instantjchem/<version number>

    • Linux - $HOME/.instantjchem/<version number>

    In case of Java Web Start installation, the <version number> changes to ws_<version number>

    You can locate the exact directory by going to "Help" and then "About Instant JChem". If you encounter issues while installing or operating IJC, first ensure that no instances of IJC are running. Then, try renaming the directory mentioned and start IJC again. This action will create a new, clean user directory. Be aware that this will reset your current settings, and you'll need to reopen your projects in the case of an update. However, your data will not be lost.

    System Encoding and Font Settings

    Users, particularly those on Windows, should verify their default system encoding and font settings, as Instant JChem adheres to these defaults unless specified otherwise. If the default settings do not meet your requirements, it's important to adjust them.

    For fonts, users should ensure that their chosen font supports the characters and symbols necessary for their work. This is especially crucial for displaying chemical structures and other specialized data correctly. Should you need to change default font settings in Instant JChem see documentation here.

    We recommend using UTF-8 as the encoding format. To do so, you can either use command line and enter -Dfile.encoding=UTF-8 or navigate to etc/instantjchem.conf and add -J-Dfile.encoding=UTF-8 among default options already specified in the instantjchem.conf file.

    Other Information