Configuration

Info

This page is still being edited and reviewed.

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.

Essential Step: Setting the Base URL

In order for file downloads links (e. g., in exporting collections) to work correctly, you have to configure the hostname of your Chemotion ELN. Set the following variable accordingly in the .env file:

Versions 1.4.1 and above

In our efforts to streamline some settings of the ELN, we introduced a new environment variable PUBLIC_URL. This variable is meant to be set to 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.

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

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.

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.

Versions 1.1.2p220401 to 1.3.0p220705

Please make sure you configure .env to contain at least two settings:

URL_HOST=<your domain here>:<port>
URL_PROTOCOL=<http or https>

Since Chemotion sends out links that point to the ELN, it needs to know where the ELN is running. So configure those two variables to make sure the ELN can construct the URLs properly. An example for localhost would look like this:

(./shared/pullin/.env:)

URL_HOST=localhost:4000
URL_PROTOCOL=http

If you are using default ports for your protocol (80 or 443) you can omit the :<port> part and use URL_HOST=localhost for example.

Setting protocol to https requires you to configure TLS on your machine (i.e. with an HTTP proxy like NGINX). It will NOT magically make it work for you. See (#setting-up-a-reverse-proxy) for more. These settings are simply used to construct URLs.

Configuration Files to Consider

To keep your installation clean, we have an overlay-based configuration system. The ELN instance starts with (reasonable) defaults and overlays all files found in ./shared/pullin/ onto the ELN application directory. As an 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). Files that you might want to configure, their locations in the ./shared/pullin folder, and the name of their template file (see below), are as follows:

Filename	Folder path + filename	Folder path + filename of the template
`.env`	`./shared/pullin/.env`	`.env.production.example`
`database.yml`	`./shared/pullin/config/database.yml`	`config/database.yml.example`
`editors.yml`	`./shared/pullin/config/editors.yml`	`config/editors.yml.example`
`welcome-message.md`	`./shared/pullin/public/welcome-message.md`	`public/welcome-message-sample.md`
`editors` (folder)	`./shared/pullin/public/editors`	`public/editors`

A template for these files 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, .env.production.example should be renamed to .env and placed in the ./shared/pullin folder.

Secret key

It is stored in the .env file and used for cookie encryption.

Username Abbreviation

Name abbreviation, like emails, are unique in the DB and can be used for sign in. The length of it can be defined in the user_props.yml configuration file:

# from the application dir (/var/www/chemotion_ELN/current) copy the config file
cp config/user_props.yml.example config/user_props.yml

# edit it
vim config/user_props.yml

# restart the application (assuming Passenger is being used)
touch tmp/restart.txt

# keep the configuration for future Chemotion ELN updates (assuming Capistrano is used)
mv config/user_props.yml /var/www/chemotion_ELN/shared/config/user_props.yml
ln -s  /var/www/chemotion_ELN/shared/config/user_props.yml /var/www/chemotion_ELN/current/config/user_props.yml

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 (optional)

This is used for sending the users an email confirmation request, reset password instructions, or other notifications. See rails docs for an explanation of the parameters.

eMail configuration parameters are set as environment variables in the .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'

File collector

This is an optional service to collect data files and distribute them to the Chemotion ELN inbox of the respective users.

(see the devices overview or doi: 10.1016/j.acax.2019.100007 )

Two options are available:

collecting attachment files from emails
collecting file or folder from local drives or over scp

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.

File collection

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

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.

Data Collector settings

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.

### example of 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, specifically version v1, seamlessly integrated through the ketcher-rails project; therefore, no additional configuration is needed. If you wish to utilize other supported structure editors, such as Ketcher v2, ChemDraw, 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.

The structure_editors.yml configuration file is located in the config folder. To configure other structure editors, follow these steps:

Navigate to the application directory (/var/www/chemotion_ELN/current).

cd /var/www/chemotion_ELN/current

Copy the example configuration file to create a new one if the file doesn't exist yet.

cp config/structure_editors.yml.example config/structure_editors.yml

Open the file and edit it. Make the necessary edits, followed by Complete structure_editors.yml example.
Restart the application (assuming Passenger is being used)

touch tmp/restart.txt

Keep the configuration for future Chemotion ELN updates (assuming Capistrano is used)

mv config/structure_editors.yml /var/www/chemotion_ELN/shared/config/structure_editors.yml
ln -s  /var/www/chemotion_ELN/shared/config/structure_editors.yml /var/www/chemotion_ELN/current/config/structure_editors.yml

Supported editors

Name	Version
ChemDraw JS	17+
Ketcher 2	2.4
Marvin JS	21.8

Complete structure_editors.yml example

```yaml
### example of structure_editors.yml
production:
  :editors:
    :chemdraw:
      :label: "ChemDrawJS"
      :license: "/chemdraw/ChemDraw-JS-License.xml" # license file of ChemDraw
      :extJs: ["/chemdraw/chemdrawweb/chemdrawweb.js"] # js of ChemDraw
    :ketcher2:
      :label: "Ketcher 2"
      :extSrc: "/editors/ketcher/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

💡 Tip: To install ChemDraw JS or Ketcher 2 library, unzip the (library).zip, and then copy the sub-folders and files to the folder which the system loads scripts.

Services

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 to use another instance of this service.

Installing ChemSpectra

Use this installation guide.

Configuration in Chemotion ELN

To configure Chemotion ELN to connect to ChemSpectra, create a configuration file:

# copy the config file from the application directory
cp /var/www/chemotion_ELN/current/config/spectra.yml.example config/spectra.yml

If you followed the above installation guide you may edit the spectra.yml as follows:

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

Restart the application (assuming Passenger is being used):

touch tmp/restart.txt

To keep the configuration for future Chemotion ELN updates (assuming Capistrano is used):

mv config/spectra.yml /var/www/chemotion_ELN/shared/config/spectra.yml
ln -s  /var/www/chemotion_ELN/shared/config/spectra.yml /var/www/chemotion_ELN/current/config/spectra.yml

Automatic startup in crontab

To make sure ChemSpectra is started on reboot you can use this BASH script in your root crontab (if required, adapt Chemotion ELN username and home directory):

#!/bin/bash

sudo -H -u production bash -c "cd /home/production/chem-spectra-app && \
  source /home/production/anaconda3/bin/activate chem-spectra && \
  gunicorn -w 4 -b 0.0.0.0:3007 server:app --daemon"

# Remember to modify path according to your installation
docker run --detach --name msconvert_docker \
    --rm -it \
    -e WINEDEBUG=-all \
    -v /home/production/chem-spectra-app/chem_spectra/tmp:/data chambm/pwiz-skyline-i-agree-to-the-vendor-licenses \
    bash

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. This might result in less uniform visuals.

By default, the render service is already configure in the docker containers for the default compose environment.

To configure the Ketcher backend render service differently, create a new configuration file called ketcher_service.yml in your config folder (by default that is ./shared/pullin/config) with the following content:

production:
  :url: 'http://ketchersvc/render'

Adjust the URL in case you run the service outside the default compose environment/at a different location.

VNC

Access remote Desktops with VNC using websockify.

adminui-vnc

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:

# copy the config file from the application directory
cp config/editors.yml.example config/editors.yml

# edit it
vim config/editors.yml

# restart the application (assuming Passenger is being used)
touch tmp/restart.txt

# keep the configuration for future Chemotion ELN updates (assuming Capistrano is used)
mv config/editors.yml /var/www/chemotion_ELN/shared/config/editors.yml
ln -s  /var/www/chemotion_ELN/shared/config/editors.yml /var/www/chemotion_ELN/current/config/editors.yml

SciFinderⁿ

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

Important note

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 oher 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 SciFinderⁿ 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 scfinder_n.yml file. After editing the scfinder_n.yml file the service needs to be restarted.

The scfinder_n.yml configuration file is in the config folder. To create the file for the first time,

# from the application dir (/var/www/chemotion_ELN/current) copy the config file
cp config/scfinder_n.yml.example config/scfinder_n.yml

# edit it
vim config/scfinder_n.yml

# restart the application (assuming Passenger is being used)
touch tmp/restart.txt

# keep the configuration for future Chemotion ELN updates (assuming Capistrano is used)
mv config/scfinder_n.yml /var/www/chemotion_ELN/shared/config/scfinder_n.yml
ln -s  /var/www/chemotion_ELN/shared/config/scfinder_n.yml /var/www/chemotion_ELN/current/config/scfinder_n.yml

### example of scfinder_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 shared/pullin/config/spectra.yml file.

production:
  :chemspectra:
    :url: "http://spectra:4000"
  :nmriumwrapper:
    :url: "https://nmrium.nmrxiv.org/releases/v0.3.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 ELN	Version of NMRium wrapper
1.5 & 1.6	0.1.0
1.7.0 - 1.7.2	0.1.0 - 0.3.0
1.7.3	0.4.0

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

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

Dynamic Welcome email and Message (optional)

caution

This feature is still in Beta version.

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. Please follow the instructions above to edit this file.

adminui-welcomemessage

note

Restarting of server might be required if you are adding the file to an already running instance.

Getting Started​

Essential Step: Setting the Base URL​

Versions 1.4.1 and above​

Versions 1.1.2p220401 to 1.3.0p220705​

Configuration Files to Consider​

Secret key​

Username Abbreviation​

User Authentication​

User Authorization​

eMail service (optional)​

File collector​

eMail Attachment collection​

File collection​

Data Collector settings​

Structure editor​

Supported editors​

Complete structure_editors.yml example​

Services​

ChemSpectra​

Installing ChemSpectra​

Configuration in Chemotion ELN​

Automatic startup in crontab​

Ketcher Renderer​

VNC​

OnlyOffice​

SciFindern​

Instance Registration​

Settings​

NMRium​

Dynamic Welcome email and Message (optional)​