Skip to main content

Configuration

Info

This page records configuration details for ELN versions released over last one year. Versions older than one year are not actively supported. However, if you still need help, kindly get in touch with the Helpdesk. This is especially true if you are using a non-dockerized installation of the ELN.

Getting Started​

The default password to the administrative account (username: ADM) of a freshly installed instance is PleaseChangeYourPassword. Please change this password as soon as possible.

Must-Do: Access URL and Secret Keys​

Used ChemCLI?

You can skip these Must-Do steps if you have installed the ELN using ChemCLI.

Variable PUBLIC_URL​

The variable called PUBLIC_URL must be set in the docker-compose.yml file. To set the variable, add it to the sections services.worker.environment and services.eln.environment just below the already present variables (such as "CONFIG_ROLE" for example) in your docker-compose.yml.

This variable is meant to set the public URL that points to your ELN installation i.e. if you type "http://my.eln" in your browser to reach the ELN, please set this variable to PUBLIC_URL=http://my.eln. This variable is used whenever the ELN has to construct absolute URLs, for example when an E-Mail is send after user registration. It is also used for the file downloads links (e. g., in exporting collections) to work correctly.

The variable deprecates the variables "HOST_URL" and "HOST_PROTOCOL" in previous versions. Those are now ignored and can be removed safely.

The PUBLIC_URL variable is a setting that tells the ELN where it can be reached. It's not a setting that magically makes it so that the ELN is reachable at the provided URL. Please see this section for more.

Variable SECRET_KEY_BASE​

The variable line - SECRET_KEY_BASE=pleasechangeme in sections services.worker.environment and services.eln.environment needs to be modified. The string pleasechangeme needs to be replaced by a random password-type string of your choice.

Variable SECRET_KEY​

The variable line - SECRET_KEY=imsupersecretandwanttobechanged in section services.converter.environment needs to be changed as well. The string imsupersecretandwanttobechanged needs to be replaced by a random password-type string of your choice.

Optional: Modify Configuration Files​

In most of the following cases, the configuration has to be modified following the instructions in this section.

To keep the installation clean, we have an overlay-based configuration system. This means that the ELN instance has a (reasonable) set of defaults that can be overwritten by user provided settings files. This is accomplished by overlaying all files found in ./shared/pullin/ onto the internal settings files.

Files that you might want to configure, their locations in the ./shared/pullin folder, and the name of their template file, are as follows:

FilenameFolder path + filenameFolder path + filename of the template
.env./shared/pullin/.env.env.production.example
database.yml./shared/pullin/config/database.ymlconfig/database.yml.example
editors.yml./shared/pullin/config/editors.ymlconfig/editors.yml.example
welcome-message.md./shared/pullin/public/welcome-message.mdpublic/welcome-message-sample.md
editors (folder)./shared/pullin/public/editorspublic/editors

The template files, i.e. files to be used as a template, can be found in our repository. Please find the release corresponding to the version of ELN you are using. Then extract the compressed source code file into a folder. In this folder, you will find the template files at the specified location; remember to rename the file as suggested.

For example, to configure the .env file, its folder path + filename would be ./shared/pullin/.env. (Here . is the current working folder, from where you run your docker compose command; in case of the ChemCLI, a shared folder should already exist inside the instances/instance-name folder). The template file, called .env.production.example should be renamed to .env and placed in the ./shared/pullin folder.

In most cases, restarting the instance is recommended to fully apply any configuration changes.

Dynamic Welcome Email and Message​

This configuration enables sending a welcome message as an email to the new users upon registration. It also displays the same content as a welcome message at the home page. The content is dynamic and can be modified and updated anytime.

adminui-welcomemessage

User Settings​

Username Abbreviation​

Name abbreviation, like emails, are unique in the database and can be used for sign in. The length of it can be defined in the user_props.yml configuration file. The template file for this is called user_props.yml.example. The modified file needs to be put in as the ./shared/pullin/config/user_props.yml file.

User Authentication​

External authentication service providers can be used from ELN v1.6. The configuration is done through the Admin Interface.

User Authorization​

This feature requires authorized access. A system administrator can grant or deny users access to the various features and functions. Please see Admin Interface > UI features

eMail Service​

This service is used for sending email confirmation requests, reset password instructions, or other notifications to Users. eMail configuration parameters are set as environment variables in the ./shared/pullin/.env file. Below is the list of available parameters:

# default url of your Chemotion ELN for http links in emails:
PUBLIC_URL='https://sld.tld'
# senders email:
DEVISE_SENDER='no-reply@sld.tld'

## SMTP config
# Remote mail server
SMTP_ADDRESS='smtp.sld.tld'
SMTP_PORT=587
# login user name & password if applicable:
SMTP_USERNAME='no-reply@sld.tld'
SMTP_PASSWORD='s3cr3tPW'
# optional, HELO domain
SMTP_DOMAIN='sld.tld'
# detect STARTTLS
SMTP_TLS=true
# authentication type ('plain' 'login' (Base64 encoded) or 'cram_md5')
SMTP_AUTH='plain'
# how OpenSSL checks the certificate  ('none' or 'peer')
SMTP_SSL_MODE='none'

See rails docs for an explanation of the parameters.

File collectors​

This service is used to collect data files and distribute them to the Chemotion ELN inbox of the respective users. See devices overview or this publication for more details. The following two options are currently available:

eMail Attachment collection​

The Chemotion ELN should be given access to an email account in which it will regularly check for incoming emails and collect the attachments. The attachments are then distributed to Chemotion ELN user by matching the additional addressee present in the To: or CC: field of the email. The sender's email address should also be one of an Chemotion ELN-registered device.

danger

All new incoming emails are processed and discarded. If the sender and other addressees are unknown to the Chemotion ELN (emails registered to Chemotion ELN accounts), then the email will be directly deleted.

Data Collection​

Files can be collected from remote storages and distributed to specific user based on the file-name matching the user's name abbreviation.

Configure the frequency for collecting the files, as well as the email access in the config/datacollectors.yml file. After editing the datacollectors.yml the worker service (DelayedJob) needs to be restarted. The background worker will collect the files at the frequencies set. If login credentials are needed, those are set in the configuration file as well.

danger

The directories watched by the collector service will be emptied at each collection i. e. all files within the watched directories will be removed.

Example of configdatacollector.yml​

The following is an example of the content for the configdatacollector.yml.

production:
  :services:
    - :name: "mailcollector"
      :cron: "5,20,35,50 * * * *" # every 15 minutes starting a xx:05
    - :name: "folderwatchersftp"
      :every: 5 # minutes
      :watcher_sleep: 30 # seconds
    - :name: "folderwatcherlocal"
      :every: 5 # minutes
      :watcher_sleep: 30 # seconds
    - :name: "filewatchersftp"
      :every: 2 # minutes
    - :name: "filewatcherlocal"
      :every: 2 # minutes

  ## Chemotion ELN email account
  :mailcollector:
    :server: "imap.server.de"
    :mail_address: "service@mail"
    :password: "password"
    # :port: 993 default
    # :ssl: true default
    :aliases:
      - "alias_one@kit.edu"
      - "alias_two@kit.edu"

  ## File collection over ssh with password
  :sftpusers:
    - :user: "user1"
      :password: "pass"
    - :user: "user2"
      :password: "pass"

  # Dir of ssh keys for data collection over sftp
  :keydir: "config/data_collector_keys"

  # Allowlist of dir paths for local data collection
  :localcollectors:
    - :path: "<%= Rails.root.join(*%w[tmp datacollector]).to_s %>"

For each registered device, a collection job can be set up through the administrator interface:

adminui-datacollector

Structure editor​

The default structure editor for Chemotion ELN is Ketcher version 1. It is seamlessly integrated through the ketcher-rails project and therefore no additional configuration is needed. If you wish to utilize other supported structure editors, such as Ketcher v2 or Marvin JS, additional configuration is required. In such cases, you'll need to adjust the necessary files and, potentially, provide a license. Please be aware that any modifications to the structure_editors.yml file will necessitate a service restart for the changes to take effect.

For the detail supported versions of the structure editors, please refer to the release note of Chemotion ELN.

Setup​

An additional configuration is required in the structure_editors.yml file following the steps described above to setup the additional structure editors. You will also have to put the resource files/folders/license at the required location(s). You can follow these steps to accomplish the same:

  1. The configuration file is called structure_editors.yml and is located in the ./shared/pullin/config folder. You will also need to create a folder called editors in the ./shared/pullin/public folder. The template file is called structure_editors.yml.example. You can get this template file quickly by running the following command.
wget  https://raw.githubusercontent.com/ComPlat/chemotion_ELN/vM.m.n/config/structure_editors.yml.example
# Here, replace the version tag (`vM.m.n` with your current version)
  1. To setup the supported editors, unzip the editor's zip file, and then copy the sub-folders and files to the folder which the system loads the editors. If you wish to have multiple editors available, you can create a sub-folder for each editor. For example, you can create a folder called ketcher2 in the ./shared/pullin/public/editors folder and copy the extracted files there. Similarly, create another folder called editor-abc for another editor.

For example, for Ketcher2 (version 2.24.0), you can run the following commands to download and extract the source code.

wget https://github.com/epam/ketcher/releases/download/v2.24.0/ketcher-standalone-2.24.0.zip
rm -rf shared/pullin/public/editors/ketcher2 # remove existing installation
unzip ketcher-standalone-2.24.0.zip -d shared/pullin/public/editors/ketcher2
  1. Edit your structure_editors.yml to reflect this new location. For example, its contents would be similar to the following:
### example of structure_editors.yml
production:
  :editors:
    :ketcher2:
      :label: "Ketcher 2"
      :extSrc: "/editors/ketcher2/standalone/index.html"
    :marvinjs:
      :label: "MarvinJS"
      :license: "license file" # license file of MarvinJS
      :extJs: ["external javascript files to be included"] # js of MarvinJS
      :extSrc: "external file" # file of MarvinJS

The compatibility table for recommended versions of Ketcher 2 to be used with the ELN is as follows:

ELN versionKetcher 2 release
1.10.52.24.0
1.10.22.21.0
1.9.32.18.0
  1. Restart the ELN.

Enable​

Given that the supported editor is disabled by default, administrators have the capability to enable it once the setting is completed. For further information, please refer to the Admin Interface > UI features for further information.

ChemSpectra​

If you are using the docker production setup, the service is already installed and configured, but you can still decide to overwrite the configuration file and use another instance of this service. The instructions to install another instance are available here. Then you can modify the spectra.yml file in the located in the ./shared/pullin/config folder. If you followed the aforementioned installation guide you may edit the spectra.yml to look as follows. Then, as always, restart the ELN.

production:
  :url: "127.0.0.1"
  :port: "3007"

Ketcher Renderer​

The Ketcher backend render service is used to render molecules on the backend. It is optional and the ELN will fall back to a different rendering mechanism if the service can not be reached. However, this might result in less uniform visuals. By default, the render service is already configured if you are using the default docker-compose.yml file (or the ChemCLI installation).

To configure the Ketcher backend render service differently, create a new configuration file called ketcher_service.yml in the ./shared/pullin/config folder and modify the URL to point towards a different location.

production:
  :url: "http://ketchersvc/render"

VNC​

Access remote Desktops with VNC using websockify. A VNC server needs to be installed on each remote machine. Settings that need to be done are described in Admin Interface > noVNC settings.

OnlyOffice​

Install OnlyOffice instance on a server. Then modify the editors.yml in the ./shared/pullin/config folder.

SciFindern​

Chemotion ELN provides users with an easy way to query information in SciFindern by using an API. To enable the use of the API, your institute needs to have a regular SciFindern license. For each ELN instance, a registration at CAS is needed.

Important

At the moment, CAS offers a process for Chemotion users in Germany to request SciFinder access through the API. This is managed by the consortium HBZ. For all other institutions not located in Germany: please let us know about your need to integrate the SciFinder API - we will try to clarify the options with CAS.

Instance Registration​

For requesting a license for SciFindern API use in Chemotion, please send a short request including the following information to nicole.jung@kit.edu.

  • Institution
  • Redirect URL pattern list
    • The URL patterns represent the domain names that you will use to host your ELN server. The patterns may use standard wildcard characters (for example, '*' for 0 or more characters).  Be sure to include all environments (including dev, test, etc.) that you might provision.
  • Contact information

Once the process is complete, you will receive a Client ID which you can enable the feature by following the "Settings" section below.

Settings​

To enable this feature, the necessary information needs to be configured in the scifinder_n.yml file in the ./shared/pullin/config folder.

### example of scifinder_n.yml
production:
  :provider:
    :metadata: "api/oauth2/metadata" # DON'T CHANGE
    :host: "https://scifinder-n.cas.org" # DON'T CHANGE
    :client_id: "" # the client id you received
    :redirect: "sfn_cb" # DON'T CHANGE
    :redirect_host: "localhost" # your server

NMRium​

Starting from Chemotion ELN version 1.5, To integrate NMRium into your instance, please add the following to the spectra.yml in the ./shared/pullin/config folder.

production:
  :chemspectra:
    :url: "http://spectra:4000"
  :nmriumwrapper:
    :url: "https://nmrium.nmrxiv.org/releases/v0.8.0/"

Here the nmriumwrapper.url value depends on the version of Chemotion ELN you are using. The compatibility between the ELN and the wrapper is as follows:

Version of Chemotion ELNVersion(s) of NMRium wrapper
1.5 & 1.60.1.0
1.7.0 - 1.7.20.1.0 - 0.3.0
1.7.3 - 1.8.10.4.0
1.8.20.5.0
1.9.3 & 1.10.50.4.0 - 0.8.0

So, if you are using e.g. ELN version 1.10.5, please nmriumwrapper.url to https://nmrium.nmrxiv.org/releases/v0.8.0/.

To be able to access these URLs successfully, you must register with the hosting service. Please contact the Helpdesk or see here for more details.

QR, Barcode and Datamatrix Stickers​

The ELN has ability to produce QR codes, Barcodes and Datamatrix codes, that can then be laid out on a PDF for printing on paper and stickers. A configuration file defines how each code type is displayed. Below is an example of the entire configuration file, which includes settings for QR code, DataMatrix code, and Barcode:

{
  "QR code": {
    "code_type": "qr_code",
    "code_image_size": 30,
    "name": true,
    "short_label": true,
    "external_label": true,
    "code_log": true,
    "molecule_name": true,
    "displaySample": true,
    "text_position": "below",
    "width": 100
  },
  "Data Matrix code": {
    "code_type": "data_matrix_code",
    "code_image_size": 30,
    "name": true,
    "short_label": true,
    "external_label": true,
    "code_log": true,
    "molecule_name": true,
    "displaySample": true,
    "text_position": "below",
    "width": 100
  },
  "Bar code": {
    "code_type": "bar_code",
    "code_image_size": 100,
    "name": true,
    "short_label": true,
    "external_label": true,
    "code_log": true,
    "molecule_name": true,
    "displaySample": true,
    "text_position": "below",
    "width": 100
  }
}

Main parameters​

  • code_type: Must be qr_code, bar_code, or data_matrix_code.

  • code_image_size Size ratio of the code image, between 0 and 100.

    • Note: If code_image_size > 30, the text_position is automatically set to below.

  • text_position: below or right.

  • width: Page width in millimeters.

  • name, short_label, external_label, molecule_name, code_log, displaySample: Boolean flags to include or exclude specific elements.

N.B. The variable displaySample will be renamed to display_sample in future releases (releases after v1.10.5).

Validation rules​

Invalid values (e.g., code_image_size > 100 or unsupported code_type) trigger warnings and are replaced with default values.

To customize the configuration, edit the following file in your Chemotion ELN installation: ./shared/pullin/public/json/printingConfig/defaultConfig.json.