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 ‘Image’ tab will be shown:

Clicking SELECT next to an image will download the image from Docker Hub (if not already available locally), then take you to the new container configuration screen as described below under ‘Configuring a Container’.

Recommended Images

The Recommended sub-tab shows images created for Jupyter or Streamlit 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 or Streamlit images that have been prepared in a particular way.

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.

Click ‘CREATE’ to 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.

Launch Binder

Once you click LAUNCH, the repository will be fetched if necessary and Binder will create the new image base on the source repo. Log output will be displayed during this process.

When ready, you will see the container configuration screen:

The suggested container name can be changed if you wish.

The default workspace folder path will point to a folder that does not yet exist.

When you finally run the container, generally the ‘workspace’ files implied by the Binder source will be copied into the newly-created workspace folder. The container will mount that workspace, so any changes made to the files on your local hard drive will be reflected in the container, and vice versa.

If the folder already exists and contains non-hidden files or folders, then you will be prompted to decide if you want to use the existing files/folders as the workspace, or otherwise stop the container creation so you can go back and choose a new workspace path. If you choose to use your existing files/folders then of course this ‘breaks’ the pure intention of the Binder source so you’re not really getting what the Binder author intended.

Some aspects of this workflow are different for ‘Local Folder’ source – see below.

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 to be configured the default suggested workspace folder will be exactly the local folder on your hard drive – so any changes made to your notebooks or data within the container will be immediately visible in your original local folder Binder source.

Since you have explicitly said you want to mount the local folder, ContainDS will not alert you to the fact that workspace folder is not empty (whereas it would prompt you to confirm for other Binder sources).

If ‘Mount local folder as the workspace’ is unchecked then a new non-existing folder will be suggested as the default workspace. Into it will be made a copy of the local folder’s files as they were at the time when the image was built, and this copy will be independent of the original local folder going forward.

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 Image 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.