This guide assumes you are familiar with basic operation of Git, Docker and a Linux operating system in general. Starting point is a fresh installation of a Linux operating system. This could be either a physical or virtual machine or the Microsoft Subsystem for Linux (untested). Minimal setups could start with 3 GiByte RAM and 20 GByte disk capacity, however it is advisable to assign considerably more ressources. The instructions in this guide have been tested on 64-bit Ubuntu Focal 20.04 (LTS). Depending on your base operating system, the following packages have to be installed:
The dockerized installation of ChemotionELN expects some folders to have numerical UID:GID of 1000:1000. These are usually the UID and GID of the first unprivileged user on a fresh system. Throughout this guide, we assume the login of this user to be
user1. Some additional settings can be applied to ease the management of the development system.
It is assumed that the development system is effectively operated in a safe environment by a single user. The settings proposed here should neither be applied to production machines nor in unsafe environments.
Operation of the docker subsystem normally requires elevated privileges. Although granting docker access to unprivileged users comes with a security impact, this can be justified on a development system. To grant management privileges for the docker subsystem, run the following commands:
Other Linux distributions (Debian, openSUSE) set up their docker instances differently (e.g. the group
docker may already exist). For these distributions, you may want to replace the
snap commands by :
In each case, the settings for
user1 will become effective upon the next login.
The code for a dockerized installation of ChemotionELN is currently split into two repositories:
- https://github.com/ptrxyz/chemotion containing Dockerfiles and shell scripts for dockerization
- https://github.com/ComPlat/chemotion_ELN containing the ELN source code
As a developer, you may want to replace one or both repositories by your own fork. In this case, you would have to replace the URLs in the code snippets given below. There are two flavours of dockerized setups of ChemotionELN:
- setup in development mode
- setup in production mode
The development mode setup is straight forward and requires only a few steps. The setup starts by checking out the containerization scripts in the home directory of
The next step is to execute the following code snippet:
As one of the first steps, the script
firstrun.sh will clone / check out the Chemotion_ELN source code. You would have to adjust the address if you would prefer to work on a fork of the repository. Later on, the script will be prompt you to type
continue to authorize a potentially destructive initialization of a fresh ChemotionELN database. In total, the code snippet will do the following:
- clone the ChemotionELN source code into a subdirectory
- download a specific development container image for ChemotionELN
- download a PostgreSQL container image and set up database for ChemotionELN
- set up a ChemotionELN container which mounts the source code of ChemotionELN as a volume and run it in the foreground (to daemonize it and send it to the background, add option
-dto the last command)
Thus any changes to the ChemotionELN source code in the
src directory will be reflected in the running instance. The status of the containers can be checked either with
docker ps or
ss -tlpen which displays the TCP sockets where processes are listening for connections. ChemotionELN should listen on port 4000 whereas the PostgreSQL database should listen on port 5432.
To tear things down, you can issue and the following command (in a different shell but from the same directory):
Additional possiblities to manage docker containers, images, networks and volumes are described in the Docker CLI manual.
For normal (non-development) installations in production mode, a pre-built image from DockerHub is used. The goal for this guide is to build our own production mode image instead. This means, a few manual adjustments are necessary, otherwise the pre-built image from DockerHub would be used. The procedure starts with checking out the containerization scripts (the repository checked out for a development mode setup can be re-used):
The next step is to modify the file
~/chemotion/build-chemotion/rebuild.sh. Any reference to
ptrxyz/chemotion must be updated. In this guide, all occurences are changed to
The setup continues with the following steps:
Depending on the power of you machine, this will take some time, as some packages will be compiled from source code. In the end, the production mode image should be ready. Check it with
docker images; the command should display an image tagged
VERSION being a placeholder for the exact version.
To start an instance of ChemotionELN, the file
~/chemotion/client-chemotion/docker-compose.yml must be updated manually to reflect the correct image name. Originally, the file references
ptrxyz/chemotion:VERSION in two places, which both must be updated to
user1/chemotion:VERSION. Please note that an update of the version field might be necessary as well. After the update, the production mode Chemotion_ELN can be started with the following commands:
The third command will prompt you to authorize a potentially destructive initialization of a fresh database by typing
continue. The fourth command will prompt prior to the removal of stopped containers. For a real production mode environment additional steps would be required (e.g. setup of a HTTP proxy), which is beyond the scope of this guide.