Skip to main content
Version: 1.1.1

Docker Installation

info

Documentation and processes are being reworked and improved at the moment. It may happen that you miss information. If you face problems, please let us know, we are there to support you. You may also contact us directly if you plan to install Chemotion.

Version 1.3.0p220705

info

With version 1.3.0 onwards a new CLI tool is available to support installations, upgrades and other administrative tasks. Please see the instructions page here.

To install version 1.3.0 of the ELN, we introduce the container version 1.3.0p220705. The images are available on DockerHub: https://hub.docker.com/r/ptrxyz/chemotion/tags

Fresh Installation

To install this version on a blank system, follow these steps:

  • download the docker-compose.yml to a directory of your choice:
wget https://raw.githubusercontent.com/ptrxyz/chemotion/latest-release/docker-compose.yml
  • download all images and create the containers, data volumes and networks by running this command in the same folder you downloaded the compose file to:
docker-compose create

Note: depending on your Compose version you might get a deprecation warning. The warning can be ignored for now, in the future, docker-compose up --no-start will be a drop-in replacement for this command.

  • Start the ELN containers with
docker-compose up

or

docker-compose up -d

(the 1st command outputs to stdout, the 2nd starts the ELN as a background service loggin to the docker's log daemon)

Upgrade from version 1.1.2

caution

Please do always create a backup of your data before upgrading. No backup - no pity.

To upgrade to 1.1.3 from 1.1.2, simply follow these steps:

  • Stop all running containers: docker-compose down --remove-orphans
  • Delete the APP volume: docker volume rm chemotion_app
  • Get the latest compose file: wget -O docker-compose.yml https://raw.githubusercontent.com/ptrxyz/chemotion/latest-release/docker-compose.yml
  • Restart the containers: docker-compose up

Version 1.1.2p220401

To install version 1.1.2 of the ELN, we introduce the container version 1.1.2p220401. Please note, the naming convention cahnged to now encode the ELN version (1.1.2) followed by a single character to denote the intended use ("p" for production, "d" for development and "e" for experimental) followed by the version of the Docker middleware in the form of "YYMMRR" with RR being an increaseing integer.

info

From this version onwards, spectra analysis services will be included into the default setup. If you do not like that, you can edit the Compose file accordingly.

info

From this version onwards, we rely on Docker volumes to preserve data. Your user data will be stored in the volumes chemotion_data and chemotion_db. DO NOT delete them if you like your stuff. No backup, no pity.

Fresh Installation

To install this version on a blank system, follow these steps:

  • download the docker-compose.yml to a directory of your choice:
wget https://raw.githubusercontent.com/ptrxyz/chemotion/latest-release/docker-compose.yml
  • download all images and create the containers, data volumes and networks by running this command in the same folder you downloaded the compose file to:
docker-compose create

Note: depending on your Compose version you might get a deprecation warning. The warning can be ignored for now, in the future, docker-compose up --no-start will be a drop-in replacement for this command.

  • Start the ELN containers with
docker-compose up

or

docker-compose up -d

(the 1st command outputs to stdout, the 2nd starts the ELN as a background service loggin to the docker's log daemon)

Upgrade from 1.0.3D0.1

To upgrade from a previouse version to this release, a few manual steps have to be done. In the new release, we changed to make use of Docker volumes instead of bind mounts for all user data and shared storages. It is up to the user to transfer previous user data to these volumes. All you need to do is to copy/merge your old folders to/with the data volume (mounted at /chemotion/data in the ELN container):

  • ./shared/eln/uploads --> /chemotion/data/uploads
  • ./shared/eln/public/images --> /chemotion/data/public/images

We recommend the following steps:

  • Bring down your current instance, backup everything:
docker-compose down --remove-orphans
sudo tar cvzf /tmp/pre-upgrade.tar.gz ./db-data ./shared ./docker-compose.yml

In case anything goes wrong, you can always fall back to this backup by simply extracting the archive.

  • clean your directory, since the new containers will also write to ./shared
rm docker-compose.yml
sudo mv ./shared ./old
  • download the docker-compose.yml:
wget https://raw.githubusercontent.com/ptrxyz/chemotion/latest-release/docker-compose.yml
  • download all images and create the containers, data volumes and networks by running this command in the same folder you downloaded the compose file to:
docker-compose create
  • start a disposable sidecar container with an interactive shell attaching your old data and old db stores in addition to the storages defined in docker-compose.yml:
docker run -v $(pwd)/old:/old \
-v chemotion_data:/new \
-v $(pwd)/db-data:/old/db \
-v chemotion_db:/new/db \
-it --rm ubuntu:latest bash
  • You will find yourself in the root of a fresh container. Copy over the following files:
cp -Rf /old/eln/uploads/.        /new/uploads/
cp -Rf /old/eln/public/images/. /new/public/images/
cp -Rf /old/db/. /new/db/

Note: the point here is that you copy everything from your old uploads and public/images folder to the new location. By default those are stored in ./eln/, if you configured things differently, adjust accordingly.

  • Your data is now stored on the data volumes. Type exit to quit the interactive shell.
  • start your new instances:
docker-compose up

Configuring

To keep your new installation clean, we switched to an overlay-based configuration system. The ELN instance will from now on start with (reasonable) defaults and overlay all files found in ./shared/pullin/ onto the ELN application directory. As an example, to configure a .env file, it's filename would be ./shared/pullin/.env. Files you might want to configure:

  • .env --> ./shared/pullin/.env
  • database.yml --> ./shared/pullin/config/database.yml
  • editors.yml --> ./shared/pullin/config/editors.yml
  • welcome-message.md --> ./shared/pullin/public/welcome-message.md
  • editors-folder --> ./shared/pullin/public/editors

Have a look at the Complat/Chemotion-GitHub-Repo to get an overview where things need to be placed.

Setting the Base-URL

Please make sure you configure .env to contain at least two settings:

URL_HOST=<your domain here>:<port>
URL_PROTOCOL=<http or https>

Since Chemotion sends out links that point to the ELN, it needs to know where the ELN is running. So configure those two variables to make sure the ELN can construct the URLs properly. An example for localhost would look like this:

(./shared/pullin/.env:)

URL_HOST=localhost:4000
URL_PROTOCOL=http

Of course, if you are using default ports for your protocol (80 or 443) you can omit the :<port> part and simply use URL_HOST=localhost for example.

Note: Settings protocol to https requires you to configure TLS on your machine (i.e. with a HTTP proxy like NGINX). It will NOT magically make it work for you. Those settings are simply used to construct URLs.

Other Documentation

The new version comes with some quality-of-life changes:

  • to check the logs of a service, use either docker-compose logs or check the ./shared/logs folder.
  • to create a backup of your data, you can use the embedded Chemotion CLI tools:
docker-compose exec eln chemotion backup

This will create a backup in ./shared/backup/

  • to restore a backup, clean out your Compose-directory, keep only the backup folder and it's files in place.
docker-compose down --remove-orphans       # stop all services
docker-compose run eln chemotion restore # restore the latest backup
  • Resetting the Administrator account's password:
docker-compose exec eln chemotion resetAdminPW
  • Getting a Rails console:
docker-compose exec eln chemotion railsc
  • Getting a shell with loaded Chemotion environment variables:
docker-compose exec eln chemotion shell
  • Drop to Postgres console in the Chemotion database:
docker-compose exec eln chemotion psql
  • Display basic version information:
docker-compose exec eln chemotion info

Notes on Backups:

The backup script is meant to simplify your life a bit when it comes to backups. However it doesn't do anything magical and if it suits your needs better, you can also do manual backups. To create on, you need to dump your database, i.e. with pg_dump or by copying the chemotion_db volume when the database is not running. In addition, you need to safe all your data, that is two folders: /uploads and the /public/images (the latter being more a convenience thing preventing you from having to recreate a lots of thumbnails after restoration). The data is stored on the chemotion_data volume, so you can simply mount it somewhere and use rsync/tar/cp to copy the data. If you already have a container mounting this volume, such as (such as the eln or worker services), you can also simply use docker-compose cp or docker cp to copy the data to the host machine and do anything you like with it.

To restore a backup, invert the process: While backups can be done with running services, for restoration, you need to stop your services, then playback the SQL-dump (pg_restore/psql/copy the volume or data files back) and then playback the data using cp/tar/rsync/etc.

Version 1.0.3D0.1

With release 1.0.3D0.1, beside upgrading the ELN version to 1.0.3, we made great improvements to the Docker middleware framework. We introduce the concept of configuration landscapes as bundles of configuration files that describe a certain environment. This is a first step to enabling users to easily switch between production, testing or teaching environments with a single command.

As of now, there is only one landscape shipped with the image and we plan to add more over time depending on user needs. You can always create your own landscapes and quickly move between them. Check out the docker-compose run eln landscape command for more info.

Further, this changed the config file structure a bit. While in previous versions, the ELN configuration was stored in ./shared/config and the container configuration was stored in ./config, there is only one folder now: ./shared. We hope this change makes it more intuitive for users.

On the inside, we managed to reduce the size of our images by more than 50% by being more selective when it comes to installed packages: using multistage builds to build the big dependencies makes sure that no build artifacts are unnecessarily present in the final image. To ensure consistency we added a dependency scanner that makes sure that all dependencies are still satisfied and no libraries are missing.

Preparation

To setup the Chemotion ELN using Docker, Docker and Docker-Compose have to be installed on the host machine. Please refer to your distributions documentation on how this can be achieved. For Ubuntu-based machines, this can be found here.

In addition you need that latest version of our Docker-Compose service description as well as some scripts depending on your scenario. The file can be found here:

FileDescription
docker-compose.ymlservice description file
setup.shuse this script if you plan to setup a new Chemotion ELN instance
upgrade.shthis script shall be used to perform an upgrade of an existing instance from v0.9.1 to v1.0.3
backup.shscript to backup your data before messing things up

(For other releases, check out our repository on DockerHub1 and the archived installation on Github2) 1: Chemotion-Images hosted on DockerHub 2: Archived Documentation on Github

Download this file and place it in a separate folder (further referred to as CHEMOTION_PATH as it will contain all the service description but also Chemotion's configuration and data files):

mkdir -p $CHEMOTION_PATH
cd $CHEMOTION_PATH
curl -L -O https://raw.githubusercontent.com/ptrxyz/chemotion/v1.0.3D0.1/client-chemotion/docker-compose.yml
curl -L -O https://raw.githubusercontent.com/ptrxyz/chemotion/v1.0.3D0.1/client-chemotion/backup.sh
curl -L -O https://raw.githubusercontent.com/ptrxyz/chemotion/v1.0.3D0.1/client-chemotion/setup.sh
curl -L -O https://raw.githubusercontent.com/ptrxyz/chemotion/v1.0.3D0.1/client-chemotion/upgrade.sh

As a next step, run the setup script and follow the instructions:

cd $CHEMOTION_PATH
bash ./setup.sh

Running Chemotion

You are now ready to run the initialization. Please note that this will create a new database and delete any old database that might exist. Therefore it is curical that you do only run this command if you want to create a new instance of Chemotion.

cd $CHEMOTION_PATH
docker-compose run eln landscape deploy
docker-compose run eln init

As the previous command finishes, you are ready to start Chemotion:

docker-compose up

You will see the system logs in your terminal and 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.

To start your instance in background mode, use docker-compose up -d. The services will automatically restart when the docker daemon restarts. This can be configured by removing the lines containing restart: unless-stopped in the docker-compose.yml file or disabling autostart of your docker daemon on your system:

services:
db:
...
worker:
restart: unless-stopped
...
eln:
restart: unless-stopped
...

Please refer to the Docker documentation on how this property works: https://docs.docker.com/config/containers/start-containers-automatically/

Managing your instance

Basic Information

To get basic information about your instance, run:

docker-compose run eln info

This will output storage, memory as well as several version information and ensure the fundamentally required runtime is correct.

Getting a shell inside the container

To get access to the inside of the container, i.e to perform tasks based on the Rails console, one can use the following command:

docker-compose run eln shell

This will drop you to a root shell inside the container. You are now free to perform any administrative tasks in the container context, but be aware that all changes are ephemeral and lost when the container is stopped. To access the host file system, a mount point has to be used, i.e. such as the already configured /shared (which - by default - maps to ./shared on the host).

Backing up your data

To backup your data, it is sufficient to run the following command on your host machine (not inside the container) in the folder, where your Compose file resides:

sudo bash ./backup.sh

:::info It is adviced to setup an automatic system task (i.e. cron job) to backup regularly. This is highly system specific and thus out of the scope of this documentation. Please refer to your OS's manual to find out how to setup scheduled tasks. In addition, you should always backup before upgrading your installation. :::

Upgrading

Note: Before upgrading anything, we highly advice to create a backup (see above)! No backup? no pity! Note: This upgrade is tailored and tested for the upgrade from 0.9.1 to 1.0.3. Note: downgrading is not supported.

Stop the services: docker-compose stop --remove-orphans

To upgrade your instance place the new docker-compose.yml and upgrade.sh in the directory where the Chemotion service files reside and run

sudo bash ./upgrade.sh

This will make sure files are properly configured and the database schemes are adjusted if necessary.

Note: Without this step, the containers will refuse to start to prevent any possible damage to your installation.

Now, restart the services: docker-compose restart

Setting up a Reverse-Proxy

To make the installation available to the public, the container's ports should to be forwarded. We suggest to run NGINX as a reverse-proxy either in docker (by extending the Docker-Compose service description file) or stand-alone on the host. The application is (by default) listening on '0.0.0.0:4000'.

A demo service description as well as some sample configuration files for NGINX can be found in the Docker-Chemotion-Monorepo (https://github.com/ptrxyz/chemotion) in the sub-folder reverse-proxy.