There are two main routes for launching new containers (virtual environments): via a Docker image, or via Binder.

Docker images are ready-made computing environments that (after download) can be turned instantly into new container instances.

Binder is a mechanism where you can specify the URL to a Git repo or similar, and have a new Docker image built and then run as a container, containing all relevant files, data, and dependencies.

This article lists the options available for starting containers through either method.

Docker Images

If you click the ‘+ NEW’ button, the default ‘Docker’ tab will be shown:

Clicking SELECT next to an image that is Jupyter-compatible will take you to the new container configuration screen as described below under ‘Configuring a Container’.

Recommended Images

The Recommended sub-tab shows images created by Jupyter and shared publicly on Docker Hub. It is possible to use ContainDS to start different types of Docker container, but it is intended to start Jupyter images that have been prepared in a particular way.

Images with a Jupyter logo should be prepared in that way so are suitable for use in ContainDS. Everything in the Recommended tab can be used correctly.

You can click the All tab and then enter some text to search Docker Hub for more images – some of which may be ContainDS-ready, but it is not guaranteed unless you know where the image has come from.

My Repos

My Repos tab shows any images that you have personally uploaded to Docker Hub either privately or publicly. To view these, you may first be prompted to login to Docker Hub. You can choose to login explicitly by clicking the ‘LOGIN’ button in the top left of ContainDS.

My Images

My Images tab shows any images which are stored locally on your computer. These may have been downloaded previously when used to create other containers, or you may have cloned another image for later reuse – perhaps after installing more Python or other packages into the environment.

Configuring a Container

After clicking SELECT on a Docker image you should see the Container Configuration screen:

This is offering the opportunity to change the name of the container (a default will be provided based on the name of the image you selected). You can change it if you wish.

You also need to complete the environment/workspace pair by selecting a Workspace Path – a folder on your hard drive which should be used to store any notebook and data files. This can be a folder that already exists and contains data and ipynb files, or you can specify a completely new folder to be created by ContainDS.

Alternatively, you can select to have an ‘Integrated Workspace’. This will mean that notebook files and data are stored directly within the container, so could be lost if you delete the container.

Click ‘CREATE’ to download the image (if needed) and then start the new container.

Binder Repos

In the ‘+ NEW’ container screen, there is a Binder tab where you can enter the URL of a repo. This repo needs to be Binder-ready – i.e. contains the information needed to install dependencies and launch Jupyter.

There are several remote locations where your repo can be stored, or you can run from a local folder on your hard drive.

Remote Binder sources

Currently, you can choose between remote hosts GitHub, Gist, GitLab, an arbitrary Git repo, or a Zenodo DOI. Select the appropriate option from the dropdown. You can also select ‘Local Folder’ to build a container from a file tree on your local hard drive – see below for more details.

You can specify the branch, tag, or commit of a Git repo. If you leave this as ‘master’, for example, then ContainDS will first find out the true commit hash that currently resolves to master, and will checkout that commit directly. If an image has already been built of that commit it will be reused.

You can enter the path to a notebook file to run initially – for example, /index.ipynb.

Local Folder Binder source

In the dropdown within the Binder screen, there is a ‘Local Folder’ option. If you select that, a Browse button will be available allowing you to locate a folder on your local hard drive, or you can enter the full path directly into the text field.

The folder selected must contain a Binder-ready source tree, meaning it must have: the notebooks and/or data for your project, and also a requirements.txt or environment.yml file etc describing the dependencies that make up the necessary environment.

Mounting the local folder

If ‘Mount local folder as the workspace’ is checked, then when the container is ready the workspace folder will be a mount of the local folder on your hard drive – so any changes made to your notebooks or data within the container will be immediately visible on your hard drive folder and vice versa.

If ‘Mount local folder as the workspace’ is unchecked then a copy of the local folder’s files will be made at the time when the container is built, and this copy will be independent of the original local folder going forward. To changes made to the files inside the container will not be seen in the original local folder. This is an ‘integrated workspace’.

For more information about the difference between Integrated and Mounted workspaces see here.

Cached Images

ContainDS will build a new Docker image each time you select the same local folder in the Binder tab provided it detects changes to the local folder’s file tree (excluding files starting with a dot). It will also maintain separate images for mounted/unmounted Binder runs where the ‘Mount local folder as the workspace’ is checked/unchecked. If the files are unchanged then it will reuse the existing image.

It is possible to directly select a cached image to be used for a container, without using the Binder interface. To do that, click on the Docker tab in the ‘+ NEW’ container screen (instead of the Binder tab) and click on the Local Images tab. Your cached Binder images should be visible. If you click ‘SELECT’ on an image then the new container configuration screen should display information messages and defaults that remind you whether the image was created in ‘mounted’ or ‘unmounted’ mode.

Generally, it will make sense to respect the conditions under which the image was created, but it is possible to separate the environment from the workspace at this point. A local folder Binder that was originally mounted can be recreated as an integrated workspace – and this should start with the workspace files as they were at the time the image was created. An originally-unmounted Binder image can be connect to a live workspace on your hard drive, in which case the files that were initially copied from the local folder into the integrated workspace will be hidden.