Configuration
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.
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.
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:
Structure editorβ
Chemotion ELN uses Ketcher as the default structure editor. To use other editors, configure the required files and the license (if needed) in the structure_editors.yml
file. After editing the structure_editors.yml
the service needs to be restarted.
The structure_editors.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/structure_editors.yml.example config/structure_editors.yml
# edit it
vim config/structure_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/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
Currently supported editorsβ
Name | Version |
---|---|
ChemDraw JS | 17, 20 |
Ketcher 2 | 2.4 |
Marvin JS | 21.8 |
### 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β
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.
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
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. This is managed by the Chemotion team at KIT to facilitate the process.
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 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.1.0/"
To be able to access it successfully, you must register with the hosting service. Please see here for more details.
An alternative url for nmriumwrapper.url
is http://bare-nmrium-main.eln.hydrogen.scc.kit.edu:4080/
, which is currently hosted at KIT but comes with no guarantees.
Dynamic Welcome email and Message (optional)β
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.
Restarting of server might be required if you are adding the file to an already running instance.