Docker Installation
info
Documentation and processes are being reworked and improved at the moment. Please contact us for installation of a development version of the ELN.
Introduction#
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.
Prerequisites#
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).
Windows#
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).
With 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.
Dependencies#
WSL 2#
Start by installing WSL 2.
important
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
Next, open an Ubuntu terminal and set up a user account.
Docker Desktop#
Once you have set up WSL 2 you can install Docker Desktop and enable the WSL 2 backend in Docker Desktop.
For additional information and prerequisites regarding the installation of Docker Desktop also have a look here (the instructions above should be sufficient though).
Setup#
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 Ubuntu under /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 Ubuntu terminal.
Next, start Docker Desktop. You can confirm that Docker Desktop is running by typing docker --version in the Ubuntu terminal.
If you get a response you're now ready to run the ELN in a Docker container or in a Visual Studio Code devcontainer.
Linux#
Dependencies#
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:
- git
- docker
- docker-compose
Setup#
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 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 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:
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.
You're now ready to run the ELN in a Docker container or in a Visual Studio Code devcontainer.
macOS#
We recommend having an Ubuntu virtual machine. Then you can follow the steps from Linux installation.
ELN in a Docker container#
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
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:
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
src - 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.
Production Mode Setup#
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 user1/chemotion.
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 user1/chemotion:VERSION with 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 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.
ELN in a Visual Studio Code devcontainer#
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 client-vscode-remote-container folder:
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 workspace
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:
You are ready now. You can find more details in this link and this video.
Tools recommended for development#
Visual Studio Code#
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.)