Docker

One of the best ways to share software and software environments in a reproducible way is using Docker. We have prepared a way to set up a docker image containing homelette and all its dependencies.

Due to the way how MODELLER licenses need to be aquired for each individual user, a two step process to setting up the docker image is required:

  1. The template for the docker image that contains everything except a MODELLER license key will be pulled from DockerHub.

  2. With a valid MODELLER license key, a local image with all dependencies working will be generated.

Note

Due to the numerous dependencies installed in the Docker image, please be aware that the image is quite big (~10 GB).

Note

The databases required for using HHSuite3 are not included in the docker container due to their size.

The following sections will explain how to set up and use the docker image.

Setting up the docker image

A bash script (construct_homelette_image.sh found in homelette/docker/) has been provided which automatically pulls the latest version of the homelette_template image from DockerHub and then attempts to construct the local homelette image with the given MODELLER license key. After downloading the script from Github, run

./construct_homelette_image.sh "YOUR MODELLERKEY HERE"

Warning

The local image created by this contains your MODELLLER license key. Similarly, as you would not send your license key to others, please do not share this image with other people, including on DockerHub.

The script will fail and no local image will be constructed if the license key is not accepted by the MODELLER version in the container.

Accessing the docker image

After constructing the local homelette docker image, you can access the docker image as every other as well.

docker run --rm -it homelette

However, to make access a bit simpler, we have written a bash script (homelete.sh found in homelette/docker/) to provide different options and modes to access the docker image. There are four different modes available:

  • ./homelette.sh -m tutorial: This opens an interactive Jupyter Lab version of the tutorials.

  • ./homelette.sh -m jupyterlab: This opens an interactive Jupyter Lab session with access to homelette and all dependencies.

  • ./homelette.sh -m interacive: This opens an interactive Python interpreter session with access to homelette and all dependencies.

  • ./homelette.sh -m script: This allows the user to execute a Python script in the Docker container.

In addition, the script has the ability to make a number of directories from the host machine available to the container. Please check out ./homelette.sh -h for more details. All containers generated by this script will be removed after termination.