In order to ensure portability over operating systems, we have created a Docker image for the design space toolbox (DST3).

What is Docker?

 Docker is a computer program that performs operating-system-level virtualization. It is used to run software packages called containers. Containers are isolated from each other and bundle their own application, tools, libraries and configuration files. All containers are run by a single operating-system kernel and are thus more lightweight than virtual machines. Containers are created from images that specify their precise contents.

 Basic Usage of Docker Image DST3

To use the DST3 via Docker follow these simple steps:

1.- Install Docker

2.- Open a terminal window (macOS and Linux) or Command Prompt (Microsoft Windows)

3.- Download the DST3 image by executing following command line on the terminal window:

docker pull savageau/dst3

4.- Create a container by executing following command line:

docker run -d -p 8888:8888 savageau/dst3

5.- Open http://localhost:8888 in a browser window. If you are a Windows user and the webpage cannot be loaded, refer to additional instructions for Windows users below.

Following page should appear after performing step 5:

docker_no_host

Saving Files on Host Computer from a Docker Container

The command docker run -d -p 8888:8888 savageau/dst3 initializes a docker container that does not have access to the files of the host computer (i.e., your computer). Consequently, created notebooks and all changes to existing notebooks/files within the container will be lost after stopping the container. In order to be able to permanently save notebooks in the memory of the host computer, additional flags are required when creating a docker container from the DST3 Image. An option is to use the −−mount flag:

On Mac/Linux:

docker run -d -p 8888:8888 −−mount type=bind,source=/Users,target=/Documents/host savageau/dst3

On Windows:

docker run -d -p 8888:8888 −−mount type=bind,source=//c/Users,target=/Documents/host savageau/dst3

This command mounts the “/Users” directory (or //c/Users on Windows) of the host machine in the folder “/Documents/host” of the Docker container. Files saved under this directory will remain after stopping the DST3. If you want to mount a specific folder from your machine, replace “/Users”  by the location of the desired folder, for example “/Users/test_user/Documents”.

Stopping Docker Containers

After finishing your work with DST3, you might want to stop the container by executing following command from a terminal window:

docker rm $(docker stop $(docker ps -a -q −−filter ancestor=savageau/dst3 −−format=”{{.ID}}”))

Running containers can be listed by executing the command docker container ls:

dockercontainerls

Specific containers can also be manually stopped and removed by using commands docker stop and docker rm. We will first stop and then remove the container with the name “serene_dijkstra”:

dockerrm

Additional Instructions for Windows Users

There is a diversity of issues when using Docker for Windows. If you have a “Home” version of Windows, refer to the section “Instructions for Windows 10 Home Users” below.

Docker for Windows has known port mapping issues. However, they can be solved trivially.

The problem arises because the command docker run -d -p 8888:8888 savageau/dst3 is not mapping the port 8888 of the savageau/dst3 container to the port 8888 of the local host on Windows. As a result, the browser is unable to connect to the webpage http://localhost:8888.

The solution consists on listing all IP network configuration values by executing the command ipconfig in a command prompt window:

ipconf

Look for the IP address associated with Docker (address in within the green rectangle in the figure above), then access the DST3 by opening the port 8888 of that IP address. For example http://10.075.1:8888

Instructions for Windows 10 Home Users

Home editions of Windows do not support Docker Desktop. Instead, Docker Toolbox needs to be installed. If you are a Windows 10 Home user, the commands to download DST3, run and stop containers need to be run from within the Docker QuickStart Terminal:

dockerquickstart

Look for the “Docker QuickStart Terminal” icon on your desktop and open it. A Terminal window pops up. Execute following commands to:

Pull DST3 Image:  docker pull savageau/dst3

Start Container: docker run -d -p 8888:8888 savageau/dst3

Start Container With Access to Host Files: docker run -d -p 8888:8888 −−mount type=bind,source=//c/Users,target=/Documents/host savageau/dst3

Stop Containers:  docker rm $(docker stop $(docker ps -a -q −−filter ancestor=savageau/dst3 −−format=”{{.ID}}”))

 Once a container has been started, open following address in a browser window -preferably Chrome:

http://192.168.99.100:8888

Following page should be loaded:

docker_no_host

Optional for macOS Users: Starting and Stopping DST3 from Automator.

Automator is a macOS application for creation of workflows for automating repetitive tasks (in this specific case, starting and stopping a docker container). The icon features a robot holding a pipe, a reference to pipelines. Here we will show how to create two Automator workflows. One for launching a DST3 container and one for stopping it.

  1. Open the Automator You can find Automator by using the spotlight search function located on the right upper corner of the screen, next to the Siri icon.
  2. Then, click on “New Document”

newdocument

3. Choose “Workflow”

workflow

4. From the Menu “Actions”, click the “Utilities” icon and then double click on “Run Shell Script”:

utilities

5. Copy paste following lines of code

#!/bin/bash

/usr/local/bin/docker pull savageau/dst3

/usr/local/bin/docker run -d -p 8888:8888 −−mount type=bind,source=/Users,target=/Documents/host savageau/dst3

sleep 2s

/usr/bin/open http://localhost:8888

pasteAutomator

6. Save the Automator using the “Save…” option of the “File” menu:

save

7. Repeat steps 1 to 6 with one single line of code to create an Automator for stopping the container:

/usr/local/bin/docker rm $(docker stop $(docker ps -a -q −−filter ancestor=savageau/dst3 −−format=”{{.ID}}”))

8. After performing steps 1 through 7, two Automator icons should be available:

automators

Use them to launch and stop DST3.

Note that the creation of the Automator workflows is optional. You can always start and stop DST3 by using a terminal window and the commands provided before.

Run:

docker run -d -p 8888:8888 −−mount type=bind,source=/Users,target=/Documents/host savageau/dst3

Stop:

docker rm $(docker stop $(docker ps -a -q −−filter ancestor=savageau/dst3 −−format=”{{.ID}}”))

Support

If you need help installing the software, do not hesitate to contact Miguel Valderrama via email mavalderramagomez@ucdavis.edu or visit him at his office: Briggs Hall 230 @ UC Davis