Creating Frontends¶
This document describes basic requirements for creating a usable Frontend (also known as Whole Tale Image).
Description¶
Software environment used in research plays a vital role in Whole Tale and needs to be preserved in the same fashion as other research artifacts. Currently Whole Tale utilizes Docker containers for that purpose. Our system is designed to allow users to create and publish Docker images, which can be subsequently used as building blocks for Tales.
Due to constraints related to reproducibility we do not permit uploading raw Docker images. Instead we require users to provide a GitHub repository, that contains everything that is necessary to build a Docker image, which at a bare minimum is a Dockerfile. A reference to a GitHub url and a commit id is kept in our database as a Recipe object.
Image composition guidelines¶
Docker images in WT are built from Recipe objects, which contain necessary
information to create a local copy of an environment, where docker build
command can be executed. There is a minimum set of requirements that the
resulting Image has to fulfil:
define a single port that is going to be used to access a running container via http(s) (e.g.
EXPOSE 8888
)define a command that is executed upon container initialization (
COMMAND ["/bin/app.exe"]
)define a user that will own container session (
USER jovyan
)define a single volume that will be used as a mount point for Whole Tale FS (
VOLUME ["/home/jovyan/work"]
)
Optionally:
FROM
target should be referenced via a digest rather than a tag (currently not enforced).
Aforementioned properties can be defined by the Dockerfile, but may be overwritten through WT’s Image object, e.g.:
"config": {
"command": "/init",
"port": 8787,
"targetMount": "/home/rstudio/work",
"urlPath": "",
"user": "rstudio"
}
Notes¶
config.command
andconfig.urlPath
properties supports templating. Currentlyconfig.port
and a randomly generated can be passed via{port}}
and{{token}}
respectively. (see Example below)config options passed to Docker during a Tale initialization are currently evaluated in a following order (first on the list takes precedence):
Tale object’s
config
propertyImage object’s
config
propertyDocker image defaults
gwvolman defaults
Example Frontends¶
A basic Jupyter image that WT uses is defined here. Relevant part of the Image object:
"config": {
"command": "jupyter notebook --no-browser --port {port} --ip=0.0.0.0 --NotebookApp.token={token} --NotebookApp.base_url=/{base_path} --NotebookApp.port_retries=0",
"memLimit": "2048m",
"port": 8888,
"targetMount": "/home/jovyan/work",
"urlPath": "?token={token}",
"user": "jovyan"
}
For a full list of properties supported by config
parameter please refer to
plugin code.