Skip to main content
Version: ELN v3.x

Manual Installation using Docker

info

This install process involves direct interaction with Docker, and is targeted at advanced users who have some experience with Docker. For an easier experience, consider using ChemCLI.

In case of problems, please let the Chemotion team know; the team is there to provide support. Users can contact the team directly when planning to install Chemotion or when facing problems installing/using it.

Latest Version​

The Chemotion team distributes the ELN as Docker images for ease of distribution and use. The latest images can be found on DockerHub and installed using a docker-compose.yml file. A version of docker-compose.yml file that uses these latest images can be found here.

Fresh Installations​

Important

Certain installations may require additional/different steps. Please check this section to see if the desired version needs such treatment.

To install the latest version of Chemotion on a blank system, follow these steps:

  • download the docker-compose.yml to a directory of your choice:

    wget https://raw.githubusercontent.com/Chemotion/ChemCLI/main/payload/docker-compose.yml

  • edit the file to change these keys if they exist in the downloaded file:

    • services.worker.environment.SECRET_KEY_BASE and services.eln.environment.SECRET_KEY_BASE (both should be same)
    • services.converter.environment.SECRET_KEY

  • 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 up --no-start

  • Start the ELN containers with

    docker compose up # outputs to stdout

    or

    docker compose up -d #starts the ELN as a background service logging to the docker's log daemon
    • after a short startup period, the ELN will be available on port 4000 and can be accessed on <host IP>:4000
    • The application is running on http://localhost:4000, the seeded administration account is ADM (all caps!) with password PleaseChangeYourPassword.
    • Proceed with Configuration
info

Chemotion relies on Docker volumes to preserve data. User data will be stored in the volumes chemotion_data and chemotion_db. DO NOT delete them: Having backups is essential to making the data FAIR.

Controlling Services​

  • Services 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 the Docker daemon on the system. Please refer to the Docker documentation on how this property works.

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

  • Following additional services are included in the docker-compose.yml file.

    ServiceIntroduced in VersionOptional
    Chemotion file format converter1.4.1Yes
    Ketcher render backend (ketchersvc)1.4.1Yes
    Spectra (spectra)1.1.2p220401Yes
    NMRium1.5.0Yes

    Optional services can be disabled by removing/commenting-out their entry in the docker-compose.yml file.

Upgrades​

Important

Certain upgrades may require additional/different steps. Please check this section to see if the current version and/or desired version needs such treatment.

Before Upgrades
  • ALWAYS perform a backup before doing upgrades. The Chemotion team cannot help restore data if there is no backup and things go wrong during upgrade processes.
  • Inform your users of downtime that may accompany the upgrade.

  • Stop all running containers:

    docker compose down --remove-orphans

  • Delete the APP volume:

    docker volume rm chemotion_app

  • Follow instructions for a fresh installation in the same directory. However, the admin/user credentials and user data should remain the same as they were before the upgrade.

Managing your instance​

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

  • Getting a shell with loaded Chemotion environment variables

    This drops the user into a root shell inside the container. The user is now free to perform any administrative tasks in the container context, but should 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).

    docker compose exec eln chemotion shell

  • Getting a Ruby on Rails console:

    docker compose exec eln chemotion railsc

  • Drop to postgreSQL console in the Chemotion database

    docker compose exec eln chemotion psql

  • Display basic version information

    docker compose exec eln chemotion info

  • Resetting the Administrator account's password

    docker compose exec eln chemotion resetAdminPW

Furthermore, the docker compose logs command can be used, or the ./shared/logs folder checked, to access the Docker logs of the system.

Backing up and Restoring your data​

info

It is advised to set up 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 the OS's manual to find out how to set up scheduled tasks.

The backup process, if using ChemCLI, is described on its page.

In addition, a backup should always be performed before upgrading the installation.

Warning

Backup scripts do not backup data that resides outside Docker volumes e.g. services and shared folders. These folders need to be backed up separately.

To backup data that resides inside Docker volumes, it is sufficient to run the following command on the host machine in the folder where the Compose file resides:

docker compose run eln chemotion backup

This will place two files: backup.sql.gz and backup.data.tar.gz in the ./shared/backup folder.

To restore a backup, clean out the folder where the Compose file resides, keeping only the backup folder and its files in place. Then run the following:

docker compose down --remove-orphans                           # stop all services
docker compose run -e FORCE_DB_RESET=1 eln chemotion restore   # restore the latest backup while resetting any database corresponding to this compose file, if already created
How backup and restore works?

This backup script is meant to simplify the backup process a bit. However it doesn't do anything magical and, if it suits the situation better, manual backups are also possible. To create one, dump the database, i.e. with pg_dump or by copying the chemotion_db volume when the database is not running.


In addition, save all data in the folders: /uploads and /public/images (the latter being more a convenience thing that avoids the need to recreate a lot of thumbnails after restoration). These folders are stored in the chemotion_data volume, which can be mounted somewhere to use rsync/tar/cp to copy the data. If a container already mounts this volume (such as the eln or worker services), then docker compose cp or docker cp can simply be used to copy the data to the host machine.


To restore a backup, invert the process: stop the services, then remount the backed-up volumes. For a backup created using pg_dump, use pg_restore to restore it. Similarly, restore the data files into their destination using cp/tar/rsync etc.

Special Cases​

Only when installing or upgrading to version 1.4.1​

This is not applicable in any other case, e.g. when moving from version v1.3.1 to v1.5.1.

Finish your installation or upgrade by following the usual steps. Then configure the converter service by following the steps described here:

In short, the following steps have to be taken:

  • create a directory to hold all its configuration
  • create a user for the ELN to authenticate at the service
  • configure the ELN to use the service and the created user

These steps would boil down to this:

mkdir -p ./shared/pullin/config/
# this makes sure a configuration directory for the ELN exists

mkdir -p ./services/converter/
# this creates a directory holding service configurations

docker run --entrypoint htpasswd httpd:2 -sbn mysuser mypassword | grep ':' > ./services/converter/htpasswd
# this creates a user in the service's authentication database

cat >> ./shared/pullin/config/converter.yml <<EOF
production:
  :url: 'http://converter/'
  :profile: MYUSER
  :secret_key: MYPASS
  :timeout: 300
  :ext:
    - '.xy'
    - '.xls'
    - '.xlsx'
    - '.txt'
    - '.brml'
    - '.dta'
    - '.pssession'
EOF

Upgrading from 1.0.3D0.1 to higher versions​

To upgrade from a previous 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 storage. It is up to the user to transfer previous user data to these volumes.

  • The required action is to copy/merge the 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

The Chemotion team recommends the following steps:

  • Bring down the current instance and backup everything. In case anything goes wrong, the backup can always be used to fall back by simply extracting the archive.

      docker compose down --remove-orphans
      sudo tar cvzf /tmp/pre-upgrade.tar.gz ./db-data ./shared ./docker-compose.yml

  • clean the 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/Chemotion/ChemCLI/main/payload/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

  • This drops the user into the root of a fresh container. The point here is to copy everything from the old uploads and public/images folder to the new location. By default those are stored in ./eln/; if things were configured differently, adjust accordingly.

    cp -Rf /old/eln/uploads/.        /new/uploads/
    cp -Rf /old/eln/public/images/.  /new/public/images/
    cp -Rf /old/db/.                 /new/db/

  • The data is now stored on the data volumes. Type exit to quit the interactive shell.

  • start the new instances:

    docker compose up -d

  • after a short startup/migration period, the ELN will be available on port <host IP>:4000

  • Proceed with Configuration.