2. Running with JupyterLab¶

The following instructions describe how to run JupyterLab with OpenCMISS-Iron using Docker or Singularity.

2.1. Starting the Docker/Singularity container¶

2.1.1. Linux and Mac¶

2.1.1.1. Docker¶

docker run \
    --rm \
    --name opencmiss-iron \
    -p 10000:8888 \
    -e JUPYTER_ENABLE_LAB=yes \
    -v ~/oc/opt:/home/jovyan/work \
    -v ~/oc/usr/local:/home/jovyan/.local \
    -v ~/oc/usr/cache:/home/jovyan/.cache \
    -v ~/oc/usr/etc/jupyter:/etc/jupyter \
    -v ~/oc/usr/bin/:/usr/local/bin \
    prasadbabarendagamage/opencmiss-iron:1.0-minimal-ssh

Important

Ensure that there are no trailing spaces following the end of line backslash deliminators.

2.1.1.2. Singularity¶

SINGULARITY_JUPYTER_ENABLE_LAB=yes singularity run \
    -B ~/oc/opt:/home/jovyan/work \
    -B ~/oc/usr/local:/home/jovyan/.local \
    -B ~/oc/usr/cache:/home/jovyan/.cache \
    -B ~/oc/usr/etc/jupyter:/etc/jupyter \
    -B ~/oc/usr/bin/:/usr/local/bin \
    docker://prasadbabarendagamage/opencmiss-iron:1.0-minimal-ssh

Important

Ensure that there are no trailing spaces following the end of line backslash deliminators.

2.1.2. Windows¶

Run the following command in a PowerShell (don’t use a standard terminal, as it does not support commands that span multiple lines).

docker run `
    --rm `
    --name opencmiss-iron `
    -p 10000:8888 `
    -e JUPYTER_ENABLE_LAB=yes `
    -v c/Users/${env:UserName}/Documents/oc/opt:/home/jovyan/work `
    -v c/Users/${env:UserName}/Documents/oc/usr/local:/home/jovyan/.local `
    -v c/Users/${env:UserName}/Documents/oc/usr/cache:/home/jovyan/.cache `
    -v c/Users/${env:UserName}/Documents/oc/usr/etc/jupyter:/etc/jupyter `
    -v c/Users/${env:UserName}/Documents/oc/usr/bin/:/usr/local/bin/ `
    prasadbabarendagamage/opencmiss-iron:1.0-minimal-ssh

Important

Ensure that there are no trailing spaces following the end-of-line tilda deliminators.

2.2. Accessing JupyterLab¶

The above commands will start a JupyterLab server on port 8888 within the docker container.

A JupyterLab interactive session can be started in the browser of your host machine by copying and pasting the url with the access token (highlighted in yellow in the figure below) into a web browser (e.g. chrome).

../../_images/docker_jupyter_server_url.png Docker JupyterLab server url

2.2.1. Additional step for Docker containers¶

However, note that the above url will give a This site can’t be reached 127.0.0.1 refused to connect error. This is because the docker run command above maps port number 8888 within the container to port number 10000 on the host windows machine. Replace 8888 with 10000 in the url and the JupyterLab interactive session will load as expected in your web browser.

Singularity does not require mapping of ports.

2.3. Working with JupyterLab¶

The following resources can help you with learning the features of JupyterLab: