Development Environment
Contact us us if you're having trouble setting up your development environment.
Prerequisites
This guide assumes you are familiar with the basics of Git, Docker and a Linux operating system. Have a look at our learning resources.
Introduction
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).
In the following you find guides for setting up a dockerized development environment for the Chemotion ELN on Windows, Linux, and macOS.
Windows
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 in its repository. 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).
With 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).
Dependencies
WSL
Start by installing WSL.
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
Next, open an Ubuntu terminal and set up a user account.
Docker Desktop
Once you have set up WSL you can install Docker Desktop and enable the WSL 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 and 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 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 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 (any IDE) or in a Visual Studio Code devcontainer (recommended!).
Linux
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).
Dependencies
Docker Engine
Install Docker Engine according to the official instructions, and make sure that non-root users can issue Docker commands by following the post-installation instructions.
You're now ready to run the ELN in a Docker container (any IDE) or in a Visual Studio Code devcontainer (recommended!).
macOS
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 in its repository. Thank you!
Install Docker 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 Docker container
Start by cloning the repository. It contains the ELN's source code and Docker configuration (docker-compose.dev.yml).
From the root of the repository (i.e., pwd is chemotion_ELN),
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
docker ps
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 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 its documentation.
Dependencies
Visual Studio Code
Install Visual Studio Code (referred to as VSCode in the following) on you operating system.
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.
Setup
Start by cloning the repository. It contains the ELN's source code as well as the configuration for the devcontainer (.devcontainer/).
Start VSCode from the root of the repository (i.e., pwd is chemotion_ELN), by running
code .
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 >Dev Containers:.
VSCode will list all available commands for the Dev Containers extension.
Select >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.
Troubleshooting
Below are a few remedies you can try when you're having trouble setting up your containerized development environment.
Clean Docker
Make sure that you're working with a clean Docker system by pruning it.
Remove node_modules directory
The ELN "app" container (Dockerfile.chemotion-dev) is configured such that the node_modules directory
is kept outside of the ELN repository.
Some commands (especially when you're using npm instead of yarn) will populate
the node_modules directory inside the ELN repository, which can cause trouble.
Simply remove node_modules from the repository in that case. Similarly, it can help to remove
public/packspublic/packs-testtmp/cache/*
Use yarn not npm to handle JavaScript dependencies
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.
Ask around
Chances are someone on the team was stuck on a similar, if not the same, problem before and knows how to help you out.