Skip to main content

Prerequisites

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:

  • git
  • docker

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.

Security implications

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.

docker group#

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:

sudo bash
groupadd --system docker
usermod -G docker user1
snap disable docker
snap enable docker
exit

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 :

...
systemctl restart docker.service
...

In each case, the settings for user1 will become effective upon the next login.

Setup#

The code for a dockerized installation of ChemotionELN is currently split into two repositories:

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

Development Mode Setup#

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 user1:

cd ~
git clone https://github.com/ptrxyz/chemotion.git

The next step is to execute the following code snippet:

cd chemotion/client-chemotion-dev
./firstrun.sh
docker-compose up

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 src
  • 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 -d to 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):

docker-compose down --remove-orphans

Additional possiblities to manage docker containers, images, networks and volumes are described in the Docker CLI manual.

Production Mode Setup#

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):

cd ~
git clone https://github.com/ptrxyz/chemotion.git

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 user1/chemotion.

The setup continues with the following steps:

cd ~/chemotion/build-chemotion
git clone https://github.com/ComPlat/chemotion_ELN.git src
./rebuild.sh

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 user1/chemotion:VERSION with 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:

cd ~/chemotion/client-chemotion
mkdir -p shared db-data
docker-compose run eln init
docker container prune
docker-compose up

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.

Last updated on by Frank Broda