Documentation and processes are being reworked and improved at the moment. Please contact us for installation of a development version of the ELN.
Containers enable the use of isolated, consistent, and portable development enviromnents. When using containers for development you will not have to install and configure the Chemotion ELN locally on your machine. Instead, depencencies and configurations are maintained in container-images which you can run on your machine using Docker. This keeps your machine free of clutter, and more importantly, it can ensure consistent development environments across contributors (i.e., avoiding "works on my machine" scenarios). Have a look at this tutorial for an accessible introduction to containers.
This guide assumes you are familiar with basic operation of Git, Docker and a Linux operating system. At minimum, your hardware setup should feature 3 GB RAM and 20 GB disk capacity (it is advisable to assign considerably more ressources).
This guide will help you getting started developing with containers on Windows using
Docker Desktop along with Windows Subsystem for Linux (referred to as
WSL 2 in the following).
Docker Desktop you can work in a Linux-based development environment and run Linux-based containers while using an IDE on Windows for editing and debugging (e.g., Visual Studio Code).
The instructions have been tested on Windows 10. Your machine should run Windows 10, version 2004, Build 18362 or higher.
Start by installing
While going through the
WSL 2 installation, make sure to install
WSL 2, not
WSL 1. Also, make sure to install
Ubuntu 20.04 LTS (referred to as
Ubuntu in the following) as your Linux distribution. You may need to upgrade
Ubuntu 20.04 LTS from
WSL 1 to
WSL 2. To check if you have the correct version, open powershell and enter the comand
If this shows verion 1 for
Ubuntu 20.04 LTS upgrade to
WSL 2 with the command
Once you have set up
WSL 2 you can install
Docker Desktop and enable the
WSL 2 backend in
For additional information and prerequisites regarding the installation of
Docker Desktop also have a look here (the instructions above should be sufficient though).
Once you have
WSL 2 and
Docker Desktop installed, you can start setting up the Chemotion ELN development enviromnent.
The development enviromnent consists of the Chemotion ELN source code as well as two Docker images containing all depencencies and configurations of the Chemotion ELN runtime.
Make sure that all files you'll download in the following steps live in the Linux file system, not in your Windows file system (here's why).
The Windows file system (e.g., C: drive) is mounted into
/mnt. Therefore, store your files somewhere else than
/mnt. For example,
you could store them in your home directory (
Also, make sure that you're running all commands from a
WSL 2 terminal (
$ command prompt), i.e., from within
Ubuntu, not Windows PowerShell (
> command prompt).
You won't be able to run bash scripts from PowerShell.
On your Windows machine, open the
Docker Desktop. You can confirm that
Docker Desktop is running by typing
docker --version in the
If you get a response you're now ready to run the ELN in a Docker container or in a Visual Studio Code devcontainer.
Starting point is a fresh installation of a Linux operating system. This could be a physical or virtual machine. The instructions have been tested on 64-bit Ubuntu Focal 20.04 (LTS). The following packages have to be installed:
The dockerized installation of Chemotion ELN 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
Some additional settings can be applied to ease the management of the development system.
It is assumed that the development system is 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.
We recommend having an Ubuntu virtual machine. Then you can follow the steps from Linux installation.
operating system requirements
The code for a dockerized installation of Chemotion ELN 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 Chemotion ELN:
- 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:
The next step is to execute the following code snippet:
First, the script
firstrun.sh will clone / check out the Chemotion ELN source code.
You would have to adjust the URL 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 Chemotion ELN database.
In total, the code snippet will do the following:
- clone the Chemotion ELN source code into a subdirectory
- download a development container image for Chemotion ELN
- download a PostgreSQL container image and set up database for Chemotion ELN
- set up a Chemotion ELN container which mounts the source code of Chemotion ELN 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 Chemotion ELN 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. After the start-up you can access your fresh instance using a browser. The application is running on
http://localhost:4000, the seeded administration account is
ADM (all caps!) with password
PleaseChangeYourPassword. 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 manual installation 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 your 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 ELN, 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
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
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.
Make sure you have docker running. Create a folder where you want to keep Dockerfiles and shell scripts for dockerization and, in the terminal, clone the following repository to it:
From that folder, dive into
Run the script
createWorkspace.sh which will create your work space containing chemotion codebase. Choose the directory where you want to have your codebase. Make sure it is an empty one. Here we will create a directory in home called
When it is done,
workspace will open in VSCode. There, check the bell button in the bottom right corner for a new notification and choose
Reopen in Container. If you can't see the notification, check the bottom left side for an icon similar to
>< in green. Press the icon, this will open a menu. From the menu choose
Reopen in Container. Building the container might take a little time. Then there is a post creation step which takes a while. When it is finished, open a new terminal in VSCode. Run:
And then type quit
And then start the server. Compiling "webpacker" takes a little time so wait a little for it:
One last step. If you start applying changes, you might get the error:
FATAL: Listen error: unable to monitor directories for changes., open a terminal and run:
In addition to the tools mentioned in the development chapter you can install the VS Code Docker extension. This extension adds the functionality to build, manage, and deploy containerized applications from inside VS Code. (You need the Remote-Container extension to actually use the container as your dev environment.)