Contact us us if you're having trouble setting up your development environment.
This guide assumes you are familiar with the basics of Git, Docker and a Linux operating system. Have a look at our learning resources.
Containers enable isolated, consistent, and portable development environments. When using containers for development you will not have to install and configure the Chemotion ELN locally on your machine. Instead, dependencies and configurations are maintained in container-images which you 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).
The following instructions are tested on Windows 10 only. If you're on Windows 11, please consider contributing your experiences. You can propose additions / changes to this documentation by opening a pull request on https://github.com/ComPlat/chemotion_saurus. Thank you!
This guide will help you getting started developing with containers on Windows using
Docker Desktop along with the Windows Subsystem for Linux (referred to as
WSL 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 (e.g., Visual Studio Code).
Start by installing
While going through the
WSL 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 command
wsl.exe -l -v
If this shows version 1 for
Ubuntu 20.04 LTS upgrade to
WSL 2 with the command
wsl.exe --set-version Ubuntu-20.04 2
Once you have set up
WSL you can install
Docker Desktop and enable the
WSL 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
Docker Desktop installed, you can start setting up the Chemotion ELN development environment.
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 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 (any IDE) or in a Visual Studio Code devcontainer (recommended!).
We assume that you're on a fresh installation of a Linux operating system, either on a physical or virtual machine. The instructions have been tested on 64-bit Ubuntu Focal 20.04 (LTS) and 22.04 (LTS).
Install Docker Engine according to https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository, and make sure that non-root users can issue Docker commands: https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user.
We haven't extensively tested our containerized development environment on macOS. If you're on macOS, please consider contributing your experiences. You can propose additions / changes to this documentation by opening a pull request on https://github.com/ComPlat/chemotion_saurus. Thank you!
Install Docker (https://docs.docker.com/desktop/install/mac-install/) and run the ELN in a Docker container (any IDE) or in a Visual Studio Code devcontainer (recommended!).
Alternatively, we recommend setting up a Ubuntu virtual machine and following the Linux installation.
ELN in a Docker container
Start by cloning https://github.com/ComPlat/chemotion_ELN.
The repository contains the ELN's source code and Docker configuration (
From the root of the repository (i.e.,
you can instantiate the development environment with
docker compose -f docker-compose.dev.yml up
The previous command starts and orchestrates three containers:
- An "app" container with a runtime environment for the ELN
- A "postgres" container with the ELN's database
- A "webpacker" server
Docker will give each of these containers a unique name that you can query with
You can open an interactive bash shell in the "app" container...
docker exec -it <NAME_OF_APP_CONTAINER_FROM_DOCKER_PS> /bin/bash
...and issue commands inside the container, e.g., to set up the database...
bundle exec rake db:setup
...or run tests.
RAILS_ENV=test bundle exec rspec
To stop the development environment (i.e., shut down all three containers) run
docker compose -f docker-compose.dev.yml down
ELN in a Visual Studio Code devcontainer
If you're using Docker Desktop (opposed to the Docker Engine on Linux) make sure that Docker Desktop is running before starting the devcontainer.
Visual Studio Code devcontainers allow you to run your entire development environment inside a Docker container. For more context visit https://code.visualstudio.com/docs/devcontainers/containers.
Visual Studio Code
Install Visual Studio Code (referred to as
VSCode in the following) on you operating system: https://code.visualstudio.com.
Note that if you're on Windows, please install VSCode on Windows, not on the Ubuntu system that's running under WSL.
Once you've got VSCode running, install the
Dev Containers extension (ms-vscode-remote.remote-containers):
Start by cloning https://github.com/ComPlat/chemotion_ELN.
The repository contains the ELN's source code as well as the configuration for the devcontainer (
Start VSCode from the root of the repository (i.e.,
chemotion_ELN), by running
The VSCode IDE is now running on you host operating system.
You can open the IDE inside a running Docker container as follows.
Bring up the Command Pallet with Ctrl+Shift+P, and type
VSCode will list all available commands for the
Dev Containers extension.
>Dev Containers: Reopen in Container. Based on the configuration in the repositories
.devcontainer directory, VSCode will now build and orchestrate the containers that constitute the
development environment. This could take about an hour, depending on your system's resources.
Below are a few remedies you can try when you're having trouble setting up your containerized development environment.
Make sure that you're working with a clean Docker system: https://docs.docker.com/config/pruning/.
The ELN "app" container (
Dockerfile.chemotion-dev) is configured such that the
is kept outside of the ELN repository.
Some commands (especially when you're using
npm instead of
yarn) will populate
node_modules directory inside the ELN repository, which can cause trouble.
node_modules from the repository in that case. Similarly, it can help to remove
When you are hopelessly stuck: start over
Use the fact that everything is containerized to your full advantage. If you feel like you've painted yourself into a corner, simply start over. It's much easier to set up everything from scratch when using containers, opposed to re-installing a clean development environment on your local machine.
Chances are someone on the team was stuck on a similar, if not the same, problem before and knows how to help you out.