Installer JupyterHub pour des Notebooks hébergés sur votre serveur

Vous connais­sez sans doute déjà les note­books Jupy­ter [1], ces docu­ments web où l'on peut rédi­ger du conte­nu en Mark­down, pou­vant conte­nir des for­mules mathé­ma­tiques en LaTeX, mêlées à des cel­lules de code Python, (ou R, Julia etc.) que l'on peut exé­cu­ter au cas par cas de façon inter­ac­tive. Ils sont pas mal uti­li­sés en data science pour explo­rer un jeu de don­nées où créer un modèle de machine lear­ning pro­gres­si­ve­ment, par exemple.

Il existe de nom­breux outils en ligne comme Google Colab, Kaggle, CoCalc ou encore Bin­der qui implé­mentent leur ver­sions de Jupy­ter.

Ins­tal­ler Jupy­te­rHub sur votre ser­veur ren­dra vos note­books acces­sibles aux gens avec qui vous tra­vaillez et vous per­met­tra d'avoir un accès com­plet sur les para­mètres. Cela sera peut être l'occasion de convaincre votre labo ou votre uni­ver­si­té d'en créer une ins­tance ouverte à tous (étu­diants com­pris ;-).

Comment Installer JupyterHub ?

Il y a dif­fé­rentes façons d'installer Jupy­te­rHub sur votre ser­veur, j'ai choi­si une façon rela­ti­ve­ment stan­dard, mais si cela ne vous convient pas n'hésitez sur­tout pas à aller voir la docu­men­ta­tion de Jupy­te­rHub [3] pour vous ren­sei­gner davan­tage.

On dis­tingue deux tech­niques légè­re­ment dif­fé­rentes, sui­vant le ges­tion­naire de paquets python que vous uti­li­sez : Ana­con­da ou pip.

Pour la pré­sente démons­tra­tion, j'ai choi­si une ins­tal­la­tion sur Debian. Il vous fau­dra adap­ter les com­mandes en fonc­tion de l'OS, ou de la dis­tri­bu­tion que vous avez sous la main…

Les droits admi­nis­tra­teur sur la machine sont requis pour ins­tal­ler Jupy­te­rHub.

Anaconda

Pour ins­tal­ler Anaconda3 [2], entrez les com­mandes sui­vantes dans votre ter­mi­nal :

wget https://repo.anaconda.com/archive/Anaconda3-2020.11-Linux-x86_64.sh
sudo bash Anaconda3-2020.11-Linux-x86_64.sh

Pré­fé­rez une ins­tal­la­tion glo­bale dans /​opt/​anaconda3 pour qu'il n'y ait pas de pro­blème de droit (ce qui peut arri­ver avec l'option par défaut /​root/​anaconda3).

conda install -c conda-forge jupyterhub  # installe jupyterhub et le proxy nodejs http
conda install notebook  # utile si vous lancez des notebooks en local

Pip

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash # installe le gestionnaire de version de nodejs
sudo nvm install v12.0.0 # choisir une version qui va bien...
sudo apt install npm # installe le gestionnaire de packet de nodejs

sudo python3 -m pip install jupyterhub
sudo npm install -g configurable-http-proxy
sudo python3 -m pip install notebook # utile si vous lancez des notebooks en local

Comment créer le fichier de configuration jupyterhub_config.py ?

Dans tous les cas, géné­rez le fichier de confi­gu­ra­tion dans /​etc/​jupyterhub en entrant les com­mandes sui­vante dans le ter­mi­nal :

sudo mkdir /etc/jupyterhub
cd /etc/jupyterhub
sudo jupyterhub --generate-config

Comment gérér JupyterHub à l'aide d'un service Systemd ?

Pareille­ment, le ser­vice dif­fère sui­vant la pro­cé­dure que vous avez menée jusqu'alors.

Pour édi­ter le fichier de confi­gu­ra­tion du ser­vice, tapez la com­mande sui­vante (pour les fan de Vim 😉 )

sudo vim /etc/systemd/system/jupyterhub.service

Puis copiez l'une de confi­gu­ra­tions sui­vantes, en fonc­tion de votre ins­tal­la­tion.

Anaconda

[Unit]
Description=Jupyterhub
After=syslog.target network.target

[Service]
User=root
Environment="PATH=/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/opt/anaconda3/bin"
ExecStart=/opt/anaconda3/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py

[Install]
WantedBy=multi-user.target

Pip

[Unit] 
Description=Jupyterhub
After=multi-user.target  
[Service] 
User=root 
ExecStart=/usr/local/bin/jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
Restart=on-failure  
[Install] 
WantedBy=multi-user.target

Comment lancer le service Systemd ?

sudo systemctl daemon-reload # recharge les services disponibles après leur édition
sudo systemctl start jupyterhub.service # lance le service jupyterhub
sudo systemctl enable --now jupyterhub.service # ajoute le service jupyterhub aux applications se lançant au démarrage du serveur et lance le service

systemctl status jupyterhub.service # Vérifie que le service s'est bien lancé et qu'il est actif

Comment installer et configurer un serveur proxy HTTP avec Nginx ?

Pour accé­der au note­books depuis une URL spé­ci­fique, il vous fau­dra enre­gis­trer un nou­veau nom de domaine, ou de sous-domaine chez votre regis­trar, et confi­gu­rer votre ser­veur pour ren­voyer cette adresse vers le port où écoute Jupy­te­rHub.

sudo apt install -y nginx
sudo systemctl enable --now nginx

sudo vim /etc/nginx/sites-available/jupyterhub.example.com.conf

Conte­nu du fichier de confi­gu­ra­tion du ser­veur :

# top-level http config for websocket headers
# If Upgrade is defined, Connection = upgrade
# If Upgrade is empty, Connection = close
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# HTTP server to redirect all 80 traffic to SSL/HTTPS
server {
    listen 80;
    server_name HUB.DOMAIN.TLD;

    # Tell all requests to port 80 to be 302 redirected to HTTPS
    return 302 https://$host$request_uri;
}

# HTTPS server to handle JupyterHub
server {
    listen 443;
    ssl on;

    server_name HUB.DOMAIN.TLD;

    ssl_certificate /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem;

    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_stapling on;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security max-age=15768000;

    # Managing literal requests to the JupyterHub front end
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # websocket headers
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header X-Scheme $scheme;

        proxy_buffering off;
    }

    # Managing requests to verify letsencrypt host
    location ~ /.well-known {
        allow all;
    }
}

N'oubliez pas de rem­pla­cer 'HUB.DOMAIN.TLD' par le nom de domaine que vous avez enre­gis­trer dans votre DNS, et qui pointe vers l'IP publique du ser­veur, par exemple dans mon cas, c'est hub​.ortion​.xyz.

Si vous pré­fé­rez uti­li­ser Apache, allez voir la confi­gu­ra­tion recom­man­dée sur la doc de jupy­te­rhub [4].

Comment générer les certificat SSL avec Letsencrypt ?

sudo add-apt-repository ppa:certbot/certbot # ajoute le dépôt PPA de certbot
sudo apt-get install certbot
sudo systemctl stop nginx
certbot certonly --standalone # génère les certificats; nginx ne doit pas fonctionner en parallèle

Relancer Nginx

sudo systemctl restart nginx

Et voi­là, nor­ma­le­ment, si tout s'est dérou­lé comme pré­vu vous pou­vez doré­na­vant accé­der à votre ser­veur Jupy­te­rHub via le domaine que vous avez spé­ci­fié avec Nginx, ou via http://localhost:8000 si vous êtes en local, et com­men­cer à créer des cel­lules et coder dans vos note­books.

Les iden­ti­fiants de connec­tion sont ceux des uti­li­sa­teurs UNIX de votre ser­veur.

Si l'installation s'est mal pas­sée et que vous n'arrivez pas à cette page, n'hésitez pas à deman­der du sup­port sur le forum de Jupy­te­rHub [5].

Bonus : Comment installer le Kernel R - IRKernel ?

Pour exé­cu­ter du code R dans vos note­books, il faut ins­tal­ler le Ker­nel R.

Il faut ins­tal­ler une ver­sion de R >= 3.5.0 pour le paquet pbdZMQ.

sudo apt install -y r-base
sudo apt install -y libssl-dev # requis pour installer dev-tools
R # lance l'interpréteur de commande R

Si vous tra­vailler avec Ana­con­da, il est peut être plus simple d'installer R avec la com­mande sui­vante : (qui ins­talle la ver­sion 3.5.1)

conda install -c r r
R

install.packages(c('repr', 'IRdisplay', 'crayon', 'pbdZMQ', 'devtools'))
devtools::install_github('IRkernel/IRkernel')
IRkernel::installspec()  # pour enregistrer le Kernel R dans l'installation actuelle de R

Pour plus de détail ren­dez vous sur la doc de IRKer­nel [6] .

sudo systemctl restart jupyterhub

Ren­dez vous sur la liste com­plète des Ker­nels dis­po­nibles sur Jupy­ter [7] pour voir l’étendue des pos­si­bi­li­tés.

Nota bene

Mal­heu­reu­se­ment, Jupy­te­rHub ne per­met pas l'édition col­la­bo­ra­tive en simul­ta­né des note­books. Cette fonc­tion­na­li­té est encore en déve­lop­pe­ment.

Pour accé­der à cette fonc­tion­na­li­té, il fau­dra plu­tôt se diri­ger vers une solu­tion alter­na­tive telle que CoCalc.

J'ai ins­tal­lé Open CoCalc sur le ser­veur de Liness, (Linux Essonne, un GULL -- Groupe d'Utilisateurs de Logi­ciels Libres), et ça marche bien [8]. Il y a même un édi­teur de docu­ment LaTeX inté­gré ain­si que de nom­breux lan­gages de pro­gram­ma­tions sup­por­tés par défaut.

Mer­ci beau­coup aux relec­teurs (aze­rin, Oli­vier Dame­ron et Yoann M.) pour leurs avis éclai­rés et leur sug­ges­tions !

---

Références

• [1] Le pro­jet Jupy­ter
• [2] Ana­con­da
• [3] La docu­men­ta­tion de Jupy­te­rHub
• [4] La docu­men­ta­tion de la confi­gu­ra­tion des proxy
• [5] Le forum dis­course de Jupy­te­rHub
• [6] La docu­men­ta­tion de IRKer­nel
• [7] La liste des ker­nels dis­po­nibles
• [8] Le ser­veur CoCalc de Liness, le GULL de l'Essonne