jupiterhub-for-openbis.md

JupyterHub for openBIS

Overview

SIS provides a Docker image for the installation of a JupyterHub server, available at https://hub.docker.com/r/openbis/.

This guide explains how to modify JupyterHub docker images and save them. It is aimed at users who are not familiar with Docker, but it should not be considered a substitute of the official Docker documentation.

** **We advise non expert users, to first test the instructions provided in this guide on their local machine, to familiarise themselves with the process, before making changes on the JupyterHub server.

Docker images are stateless, which means that after rebooting all changes made will not be saved. This guarantees a stable environment, which is particularly desirable to run services.

If a user wants to introduce changes, the docker image needs to be updated. There are two possibilities for this: 

• For testing: Login into the Docker container, modify it and save the modified container as a new image. This method is not recommended for production because it is not compatible with official JupyterHub Docker image upgrades released by SIS.
• For correct maintenance: Extend the current image using a Docker recipe that includes only your changes. This method is recommended for production, because when a new official JupyterHub Docker image is released by SIS, it will be possible to quickly apply the changes to this image from the Docker recipe.

Nomenclature

Docker: A computer program that performs operating-system-level virtualisation also known as containerisation. The official website can be found here https://www.docker.com/.

Docker image: Docker images describe the environment to virtualise. Docker images are stateless.

Docker container: Docker containers provide the environment to execute the images.

Prerequisites for testing in a local environment

1. Docker environment. All examples shown below require a working docker environment. Please visit https://www.docker.com to download the Docker Community Edition for your OS.
2. JupyterHub Docker image. The jupyterhub-openbis images can be found at https://hub.docker.com/r/openbis/. They can be installed locally like any other Docker Hub image.
3. openBIS installation (optional).

How to run the official JupyterHub for openBIS image in your local machine

1. After downloading the jupyterhub-openbis, find the id of your image.

$ docker images
REPOSITORY                                              TAG                 IMAGE ID            CREATED             SIZE
openbis/jupyterhub-openbis-sis-20180405                 latest              585a9adf333b        23 hours ago        4.75GB

2. Run the image with one of the two following commands:

a. if you want to connect to your productive openBIS instance (e.g. https://openbis-elnlims.ch), use the following command:

docker run -e OPENBIS_URL=https://openbis-elnlims.ch -e JUPYTERHUB_INTEGRATION_SERVICE_PORT=8002 -e JUPYTERHUB_PORT=8000 -e CERTIFICATE_KEY=/vagrant/config/certificates/default.key -e CERTIFICATE_CRT=/vagrant/config/certificates/default.crt -p 8000:8000 -p 8081:8081 -p 8001:8001 -p 8002:8002 585a9adf333b ./vagrant/initialize/start_jupyterhub.sh

b. if you have a local openBIS installation for testing, you can run the following command:

docker run -v /Users/juanf/jupyterhub-local/home:/home -v /Users/juanf/jupyterhub-local/config/certificates:/vagrant/config/certificates -e OPENBIS_URL=https://129.132.228.42:8443 -e JUPYTERHUB_INTEGRATION_SERVICE_PORT=8002 -e JUPYTERHUB_PORT=8000 -e CERTIFICATE_KEY=/vagrant/config/certificates/default.key -e CERTIFICATE_CRT=/vagrant/config/certificates/default.crt -p 8000:8000 -p 8081:8081 -p 8001:8001 -p 8002:8002 585a9adf333b ./vagrant/initialize/start_jupyterhub.sh

[TABLE]

⚠️ **Please note the following configuration options:

1. -v /Users/juanf/jupyterhub-local/home:/home** - This option is only required if you want to store the changes you are making. You need to have a home directory for this. It is not necessary for testing, as the image will provide a default one. This directory should contain a "vagrant" sub directory.**

To stop a running docker container, run "**docker kill container_ID". **

The container_ID can be found by running the command** "docker ps".**

How to extend the official JupyterHub for openBIS image

Modify a currently running container - From UI (for users)

Please note that libraries installed in this way are NOT permanently saved. After upgrade of the image, the libraries need to be re-installed.

Check Available Python 2 Libraries

help("modules")

Add Python 2 Library

It can probably be done but we are currently not supporting it.

Check Available Octave Libraries

pkg list

Add Octave Library

It can probably be done but we are currently not supporting it.