From 0b59e56ec86bf971e518127a5e9df3acbdca1010 Mon Sep 17 00:00:00 2001
From: Marco Del Tufo <marco.deltufo@exact-lab.it>
Date: Wed, 26 Jul 2023 07:19:41 +0000
Subject: [PATCH] Update jupiterhub-for-openbis.md
---
.../jupiterhub-for-openbis.md | 233 ++++++++++--------
1 file changed, 124 insertions(+), 109 deletions(-)
diff --git a/docs/user-documentation/advance-features/jupiterhub-for-openbis.md b/docs/user-documentation/advance-features/jupiterhub-for-openbis.md
index af73ff6e7b7..7e8fd40f3c1 100644
--- a/docs/user-documentation/advance-features/jupiterhub-for-openbis.md
+++ b/docs/user-documentation/advance-features/jupiterhub-for-openbis.md
@@ -54,30 +54,25 @@ execute the images.
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.
+1. After downloading the jupyterhub-openbis, find the id of your image.
```bash
$ 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:
+2. Run the image with one of the two following commands:
-a\. if you want to connect to your productive openBIS instance (e.g.
+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
+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
@@ -115,7 +110,9 @@ It can probably be done but we are currently not supporting it.
### Check Available Octave Libraries
- pkg list
+```bash
+pkg list
+```
@@ -125,15 +122,15 @@ It can probably be done but we are currently not supporting it.
### Check Available Python 3 Libraries
- pip freeze
-
-
+```bash
+pip freeze
+```
### Add Python 3 Library
-1\. Use pip install as you would normally do. The Python 3 kernel often
+1. Use pip install as you would normally do. The Python 3 kernel often
doesn't need to be restarted to pick up new libraries, but is
recommended to do so.
@@ -148,7 +145,7 @@ recommended to do so.
### Add R Library
-1\. Use the install command as you would normally do. The R kernel needs
+1. Use the install command as you would normally do. The R kernel needs
to be restarted to pick up new libraries.
@@ -156,28 +153,34 @@ to be restarted to pick up new libraries.
Modify a currently running container - From Console (for admins)
----------------------------------------------------------------
-1\. Find the container id of the image currently running.
+1. Find the container id of the image currently running.
- $ docker ps
- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
- a2b76d1dd204 jupyterhub-openbis-sis-20180405 "./vagrant/initial..." 4 seconds ago Up 2 seconds 0.0.0.0:8000-8002->8000-8002/tcp, 0.0.0.0:8081->8081/tcp nervous_leakey
+```bash
+$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+a2b76d1dd204 jupyterhub-openbis-sis-20180405 "./vagrant/initial..." 4 seconds ago Up 2 seconds 0.0.0.0:8000-8002->8000-8002/tcp, 0.0.0.0:8081->8081/tcp nervous_leakey
+```
-2\. Log into the container.
+2. Log into the container.
- $ docker exec -it a2b76d1dd204 bash
+```bash
+$ docker exec -it a2b76d1dd204 bash
+```
### Add Python Library
Add a new library to Python 3
- # First we should move to the environment used by JupyterHub
- [root@a2b76d1dd204 /]# export PATH=/vagrant_installation/miniconda3/bin:$PATH
- [root@a2b76d1dd204 /]# export LC_ALL=en_US.utf8
- [root@a2b76d1dd204 /]# export LANG=en_US.utf8
- # Install a new python lib using pip
- [root@a2b76d1dd204 /]# python --version
- Python 3.6.4 :: Anaconda, Inc.
- [root@a2b76d1dd204 /]# pip install prettytable
+```bash
+# First we should move to the environment used by JupyterHub
+[root@a2b76d1dd204 /]# export PATH=/vagrant_installation/miniconda3/bin:$PATH
+[root@a2b76d1dd204 /]# export LC_ALL=en_US.utf8
+[root@a2b76d1dd204 /]# export LANG=en_US.utf8
+# Install a new python lib using pip
+[root@a2b76d1dd204 /]# python --version
+Python 3.6.4 :: Anaconda, Inc.
+[root@a2b76d1dd204 /]# pip install prettytable
+```
This type of changes can be validated straightaway in JupyterHub, by
just starting a Python 3 notebook. Other changes could require to reboot
@@ -194,13 +197,15 @@ lost.
Add a new library to R
- # First we should move to the environment used by JupyterHub
- [root@a2b76d1dd204 /]# export PATH=/vagrant_installation/miniconda3/bin:$PATH
- [root@a2b76d1dd204 /]# export LC_ALL=en_US.utf8
- [root@a2b76d1dd204 /]# export LANG=en_US.utf8
- # Install a new r lib using conda
- [root@a2b76d1dd204 /]# sudo conda list r-
- [root@a2b76d1dd204 /]# sudo conda install -c r -y r-base64enc
+```bash
+# First we should move to the environment used by JupyterHub
+[root@a2b76d1dd204 /]# export PATH=/vagrant_installation/miniconda3/bin:$PATH
+[root@a2b76d1dd204 /]# export LC_ALL=en_US.utf8
+[root@a2b76d1dd204 /]# export LANG=en_US.utf8
+# Install a new r lib using conda
+[root@a2b76d1dd204 /]# sudo conda list r-
+[root@a2b76d1dd204 /]# sudo conda install -c r -y r-base64enc
+```
This type of changes can be validated straightaway in JupyterHub, by
just starting a R notebook. Other changes could require to reboot
@@ -210,26 +215,22 @@ JupyterHub.
### Save the state of a running container as a new imageÂ
-Â
-
If you know that you have made significant changes that you want to keep
until you build a new docker recipe, you have the option to save the
running container as a new image.Â
-Â
-
- bs-mbpr28:jupyterhub_reference_installation juanf$ docker ps
- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
- a2b76d1dd204 jupyterhub-openbis-sis-20180405 "./vagrant/initial..." 37 minutes ago Up 37 minutes 0.0.0.0:8000-8002->8000-8002/tcp, 0.0.0.0:8081->8081/tcp lucid_stonebraker
-
- $ docker commit a2b76d1dd204 jupyterhub-openbis-sis-juanextensions-20180406
- sha256:5dd0036664c75a21d6a62b80bf5780e70fcad345bb12a7ad248d01e29a3caa99
- $ docker images
- REPOSITORY TAG IMAGE ID CREATED SIZE
- jupyterhub-openbis-sis-juanextensions-20180406 latest 5dd0036664c7 4 seconds ago 4.75GB
- jupyterhub-openbis-sis-20180405 latest 585a9adf333b 23 hours ago 4.75GB
+```bash
+bs-mbpr28:jupyterhub_reference_installation juanf$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+a2b76d1dd204 jupyterhub-openbis-sis-20180405 "./vagrant/initial..." 37 minutes ago Up 37 minutes 0.0.0.0:8000-8002->8000-8002/tcp, 0.0.0.0:8081->8081/tcp lucid_stonebraker
-
+$ docker commit a2b76d1dd204 jupyterhub-openbis-sis-juanextensions-20180406
+sha256:5dd0036664c75a21d6a62b80bf5780e70fcad345bb12a7ad248d01e29a3caa99
+$ docker images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+jupyterhub-openbis-sis-juanextensions-20180406 latest 5dd0036664c7 4 seconds ago 4.75GB
+jupyterhub-openbis-sis-20180405 latest 585a9adf333b 23 hours ago 4.75GB
+```
Extend a docker image using a docker recipe (for maintenance)
-------------------------------------------------------------
@@ -240,13 +241,15 @@ latest official docker image distributed by SIS.
Using our last example, let's create a file called "Dockerfile" and with
the content shown below.
- # vim:set ft=dockerfile:
- FROM openbis/jupyterhub-openbis-sis-20180405
- ## Adding Python 3 library
- RUN export PATH=/vagrant_installation/miniconda3/bin:$PATH && \
- export LC_ALL=en_US.utf8 && \
- export LANG=en_US.utf8 && \
- pip install prettytable
+```bash
+# vim:set ft=dockerfile:
+FROM openbis/jupyterhub-openbis-sis-20180405
+## Adding Python 3 library
+RUN export PATH=/vagrant_installation/miniconda3/bin:$PATH && \
+ export LC_ALL=en_US.utf8 && \
+ export LANG=en_US.utf8 && \
+ pip install prettytable
+```
Please change the name of the image in the file to the one you are
using.
@@ -256,51 +259,56 @@ the official repository.
> :warning: **It is best practice to include both the name of the user and the creation date in the image name. This will help when dealing with many versions created by different users at different times**.
- $ docker build -t jupyterhub-openbis-sis-juanextensions-recipe-20180406 .
- Sending build context to Docker daemon 4.957GB
- Step 1/2 : FROM openbis/jupyterhub-openbis-sis-20180405
- ....
- Step 2/2 : RUN export PATH=/vagrant_installation/miniconda3/bin:$PATH && export LC_ALL=en_US.utf8 && export LANG=en_US.utf8 && pip install prettytable
- ....
- Successfully tagged jupyterhub-openbis-sis-juanextensions-recipe-20180406:latest
- Â
+```bash
+$ docker build -t jupyterhub-openbis-sis-juanextensions-recipe-20180406 .
+Sending build context to Docker daemon 4.957GB
+Step 1/2 : FROM openbis/jupyterhub-openbis-sis-20180405
+....
+Step 2/2 : RUN export PATH=/vagrant_installation/miniconda3/bin:$PATH && export LC_ALL=en_US.utf8 && export LANG=en_US.utf8 && pip install prettytable
+....
+Successfully tagged jupyterhub-openbis-sis-juanextensions-recipe-20180406:latest
+Â
The new image is now available and can be started as described above.
- $ docker images
- REPOSITORY TAG IMAGE ID CREATED SIZE
- jupyterhub-openbis-sis-juanextensions-recipe-20180406 latest a0106501b223 3 minutes ago 4.75GB
- openbis/jupyterhub-openbis-sis-20180405 latest 585a9adf333b 23 hours ago 4.75GB
+$ docker images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+jupyterhub-openbis-sis-juanextensions-recipe-20180406 latest a0106501b223 3 minutes ago 4.75GB
+openbis/jupyterhub-openbis-sis-20180405 latest 585a9adf333b 23 hours ago 4.75GB
+```
+
How to start a jupyterhub-openbis docker image on a productive JupyterHub server
--------------------------------------------------------------------------------
-
-
> :warning: **You can only have **ONE**Â jupyterhub-openbis image running on a server at one given time, since JupyterHub makes use of certain ports on the machine that are also configured in openBIS**.
1. Find the jupyterhub-openbis-start.sh file in your server (please ask
your admin).
-2\. Find the container id of the image that is currently running.
+2. Find the container id of the image that is currently running.
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a2b76d1dd204 jupyterhub-openbis-sis-20180405 "./vagrant/initial..." 4 seconds ago Up 2 seconds 0.0.0.0:8000-8002->8000-8002/tcp, 0.0.0.0:8081->8081/tcp nervous_leakey
-3\. Stop the current container.
+3. Stop the current container.
$ docker kill a2b76d1dd204
a2b76d1dd204
-4\. Edit the  jupyterhub-openbis-start.sh file in your server and update
+4. Edit the  jupyterhub-openbis-start.sh file in your server and update
the name of the image it runs to the one of your choice
- docker run -v /Users/juanf/Documents/programming/git/jupyter-openbis-integration/jupyterhub_reference_installation/home:/home -v /Users/juanf/Documents/programming/git/jupyter-openbis-integration/jupyterhub_reference_installation/vagrant/config/certificates:/vagrant/config/certificates -e OPENBIS_URL=https://129.132.229.37: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 jupyterhub-openbis-sis-20180405 ./vagrant/initialize/start_jupyterhub.sh
+```bash
+docker run -v /Users/juanf/Documents/programming/git/jupyter-openbis-integration/jupyterhub_reference_installation/home:/home -v /Users/juanf/Documents/programming/git/jupyter-openbis-integration/jupyterhub_reference_installation/vagrant/config/certificates:/vagrant/config/certificates -e OPENBIS_URL=https://129.132.229.37: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 jupyterhub-openbis-sis-20180405 ./vagrant/initialize/start_jupyterhub.sh
+```
-5\. Start the new image.
+5. Start the new image.
- $ ./jupyterhub-openbis-start.sh
+```bash
+$ ./jupyterhub-openbis-start.sh
+```
Other useful Docker commands
----------------------------
@@ -309,31 +317,39 @@ Other useful Docker commands
> :warning: **It is best practice to include both the name of the user and the creation date in the image name. This will help when dealing with many versions created by different users at different times**.
- $ docker save jupyterhub-openbis-sis-20180405 > jupyterhub-openbis-sis-20180405.tar
- $ ls -lah
- total 9681080
- -rw-r--r-- 1 juanf 1029 4.6G Apr 5 15:38 jupyterhub-openbis-sis-20180405.tar
+```bash
+$ docker save jupyterhub-openbis-sis-20180405 > jupyterhub-openbis-sis-20180405.tar
+$ ls -lah
+total 9681080
+-rw-r--r-- 1 juanf 1029 4.6G Apr 5 15:38 jupyterhub-openbis-sis-20180405.tar
+```
### Load an image from a tar file
- $ docker load < jupyterhub-openbis-sis-20180405.tar
- 8feeda13d3ce: Loading layer [==================================================>] 27.65kB/27.65kB
- 622cd2c170f3: Loading layer [==================================================>] 152MB/152MB
- 633fa40a6caa: Loading layer [==================================================>] 2.048kB/2.048kB
- 7219a9159e4f: Loading layer [==================================================>] 223.9MB/223.9MB
- 678b55e862c7: Loading layer [==================================================>] 4.377GB/4.377GB
- Loaded image: jupyterhub-openbis-sis-20180405:latest
- $ docker images
- REPOSITORY TAG IMAGE ID CREATED SIZE
- jupyterhub-openbis-sis-20180405 latest 585a9adf333b 24 hours ago 4.75GB
+```bash
+$ docker load < jupyterhub-openbis-sis-20180405.tar
+8feeda13d3ce: Loading layer [==================================================>] 27.65kB/27.65kB
+622cd2c170f3: Loading layer [==================================================>] 152MB/152MB
+633fa40a6caa: Loading layer [==================================================>] 2.048kB/2.048kB
+7219a9159e4f: Loading layer [==================================================>] 223.9MB/223.9MB
+678b55e862c7: Loading layer [==================================================>] 4.377GB/4.377GB
+Loaded image: jupyterhub-openbis-sis-20180405:latest
+$ docker images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+jupyterhub-openbis-sis-20180405 latest 585a9adf333b 24 hours ago 4.75GB
+```
### Remove an image
- $ docker rmi jupyterhub-openbis-sis-juanextensions-recipe-20180406
+```bash
+$ docker rmi jupyterhub-openbis-sis-juanextensions-recipe-20180406
+```
### Remove all stopped containers
- $ docker rm $(docker ps -aq)
+```bash
+$ docker rm $(docker ps -aq)
+```
openBIS ELN Integration Configuration
-------------------------------------
@@ -342,32 +358,32 @@ On the openBIS end, what needs to be done is to append the following
lines into your ELN instance profile:
servers/core-plugins/eln-lims/1/as/webapps/eln-lims/html/etc/InstanceProfile.js
- # Ansible yml syntax, replace the variables in the double curly braces by the appropriate values:
- this.jupyterIntegrationServerEndpoint = "https://{{ openbis_jupyterhub_hostname }}:{{ openbis_jupyterhub_communication_port }}";
- this.jupyterEndpoint = "https://{{ openbis_jupyterhub_hostname }}/";
+```js
+# Ansible yml syntax, replace the variables in the double curly braces by the appropriate values:
+this.jupyterIntegrationServerEndpoint = "https://{{ openbis_jupyterhub_hostname }}:{{ openbis_jupyterhub_communication_port }}";
+this.jupyterEndpoint = "https://{{ openbis_jupyterhub_hostname }}/";
- # Example:
- this.jupyterIntegrationServerEndpoint = "https://jupyterhub-demo.labnotebook.ch:80";
- this.jupyterEndpoint = "https://jupyterhub-demo.labnotebook.ch/";
+# Example:
+this.jupyterIntegrationServerEndpoint = "https://jupyterhub-demo.labnotebook.ch:80";
+this.jupyterEndpoint = "https://jupyterhub-demo.labnotebook.ch/";
On the jupyterhub end, the docker command would then look as follows:
- docker run -e OPENBIS_URL=https://{{ openbis_public_hostname }} -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 {{ openbis_jupyterhub_communication_port }}:8002 585a9adf333b ./vagrant/initialize/start_jupyterhub.sh
+docker run -e OPENBIS_URL=https://{{ openbis_public_hostname }} -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 {{ openbis_jupyterhub_communication_port }}:8002 585a9adf333b ./vagrant/initialize/start_jupyterhub.sh
- # Example:
- openbis_public_hostname: openbis-test.ethz.ch
- openbis_jupyterhub_hostname: jupyterhub-test.ethz.ch
- openbis_jupyterhub_communication_port: 80
+# Example:
+openbis_public_hostname: openbis-test.ethz.ch
+openbis_jupyterhub_hostname: jupyterhub-test.ethz.ch
+openbis_jupyterhub_communication_port: 80
The only port you need to open on your jupyterhub instance is the one
matching {{Â openbis\_jupyterhub\_communication\_port }}. Using
firewall-cmd this would look as follows:
- firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="{{ openbis_jupyterhub_openbis_hostname }}" port protocol="tcp" port="{{ openbis_jupyterhub_communication_port }}" accept'
-
-
+firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="{{ openbis_jupyterhub_openbis_hostname }}" port protocol="tcp" port="{{ openbis_jupyterhub_communication_port }}" accept'
+```
Troubleshooting Connectivity to openBIS
---------------------------------------
@@ -401,7 +417,6 @@ just log in to JupyterHub there is a new session available that needs to
be handed over to the Jupyter server. For that just stop and start it
again.Â
-
Step 1 :Â Go to your control panel clicking on the button of the top
right corner.
--
GitLab