Installation de jupyterhub sous docker

Docker est un outil de virtualisation d'application léger et très performant. Il permet de bénéficier d'un environnement jupyterhub indépendant du reste du système.

JupyterHub est un outil permettant d'ajouter une fonctionnalité multi-utilisateurs à Jupyter. nbgrader s'intègre à cette configuration afin de rendre automatique la soumission et la récupération des travaux. Il nécessite par contre l'utilisation dans le lycée d'un serveur hébergeant la solution. Disposer d'un tel outil permet d'éviter d'avoir à installer jupyter en local car un accès distant via le navigateur suffit.

La procédure proposée ci-dessous permet d'installer automatiquement un serveur JupyterHub et d'importer automatiquement une liste de comptes profs et élèves au format CSV pour une utilisation immédiate.

Méthode : Installation de docker

Pour installer docker sur Ubuntu 18.04 serveur,

se connecter avec le compte créé lors de l'installation
taper les commandes suivantes. Saisissez votre mot de passe à la première commande

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -a -G docker VOTRE_COMPTE

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -a -G docker VOTRE_COMPTE

puis ajoutez votre compte utilisateur au groupe docker qui a été créé

Fermez et ré-ouvrez votre session.

Pour installer docker sous macOS, rendez-vous à cette adresse pour télécharger l'application docker. Elle se lance comme une application classique.

Méthode : Installation de jupyterHub

Pour créer un container faisant tourner l'image jupyterhub personalisée, tapez la commande

docker run -it -p 8000:8000 --name jhub wawachief/jupyterhub

docker run -it -p 8000:8000 --name jhub wawachief/jupyterhub

Tapez CTRL-C pour quitter le container.

Votre serveur jupyterhub est installé et opérationnel sur le port 8000. Pour le tester, lancez votre navigateur à l'adresse

http://127.0.0.1:8000 ou http://votre_adresse_ip:8000

des exemples permettant de tester les modules préinstallés sont disponibles pour les comptes professeurs.

Complément : Gérer le container

Si vous quittez le container, le serveur jupyterhub ne tourne plus. Pour le relancer à nouveau, il suffit de relancer le container par la commande :

docker start jhub 

docker start jhub

jhub étant le nom choisi par le paramètre --name lors de la création du container.

Pour arrêter le container, tapez

docker stop jhub 

docker stop jhub

Si vous souhaitez effacer le container - et les données qu'il contient !! - et repartir sur une image propre, tapez

docker rm jhub

docker rm jhub

Vous pouvez maintenant recréer un nouveau container à partir de l'image jhub_image par la commande docker run exposée ci-dessus. Pour conserver les données hors du container - recommandé pour une installation serveur - référezv-ous au paragraphe persistance des données ci-dessous.

Remarque :

Le but de cette page n'est pas de faire un tutoriel complet sur docker. Je vous recommande pour en savoir plus de lire la documentation de docker afin de pouvoir tirer le maximum de superbe outil.

Fondamental : Comptes utilisateurs

Par défaut, l'image docker contient un compte administrateur jupyterhub :

login : adminjh

pass : wawa

Ce compte est aussi administrateur du container : vous pouvez ouvrir un terminal et taper sudo su pour abtenir les droits root

Vous pouvez utiliser les comptes présents dans le fichier CSV. Il contient

20 comptes élèves : eleve1 jusqu'à eleve20, mot de passe toto
3 comptes profs : prof1 à prof3, mot de passe wawa

Pour créer de nouveaux comptes, créez un fichier CSV (par exemple mesComptes.csv) au même format décrit ci-dessus et déposez-le sur le serveur jupyterhub dans l'espace de l'administrateur adminjh (bouton upload). Ouvrez ensuite une console puis tapez la commande

sudo /usr/bin/import_comptes.sh mesComptes.csv

sudo /usr/bin/import_comptes.sh mesComptes.csv

Si vous vous connectez en tant que professeur, deux activités exemples sont déjà présentes et vous permettent de tester l'outil nbgrader en suivant la démarche décrite dans la section suivante.

Attention :

Modifiez le mot de passe adminjh pour une utilisation en production !

Pour se faire,

connectez-vous adminjh
ouvrez un terminal depuis jupyter par New / Terminal
tapez sudo passwd adminjh, tapez le mot de passe courant puis 2 fois le nouveau mot de passe

Procédez de manière identique pour changer le mot de passe d'un autre utilisateur.

Gérer la persistance des données

Les volumes docker

Les volumes docker sont des dossiers spéciaux qui permettent le partage de données entre un ou plusieurs containers, ainsi que la persistance de celles-ci. Voici quelques propriétés intéressantes à connaître :

Les volumes sont initialisés à la création du container. Si l'image de base contient des données au point de montage spécifié, celles-ci sont copiés dans le volume lors de son initialisation. On peut donc ajouter des containers à volonté selon les points de l'arborescence qu'on souhaite rendre persistants ou partagés.
Les volumes de données peuvent être partagés entre plusieurs containers.
Les données sont conservées même si le container est détruit.

Nous allons voir dans la pratique comment utiliser les volumes pour mettre en production un serveur jupyterhub

Méthode : Création des volumes

Si vous mettez en place un serveur en production, vous voudrez que vos données survivent même si vous effacez le container pour en reconstruire un propre à partir d'une image. Les volumes docker sont vos amis ! Grâce à eux, vous pourrez externaliser le stockage de certains dossiers hors du container. Pour cette installation de jupyterhub, je recommande deux volumes

un volume pour les espaces personnels de stockage (jh_home)
un volume pour la zone d'échange nbgrader (jh_exchange)

Pour créer ces deux volumes, tapez les commandes suivantes

docker volume create jh_home
docker volume create jh_exchange

docker volume create jh_home
docker volume create jh_exchange

Pour créer un container utilisant ces volumes, il faut juste ajouter le paramètre

-v NOM_VOLUME:ARBO_DANS_CONTAINER :

docker run -it --name jhub -p 8000:8000 -v jh_home:/home -v jh_exchange:/srv/nbgrader/exchange wawachief/jupyterhub

docker run -it --name jhub -p 8000:8000 -v jh_home:/home -v jh_exchange:/srv/nbgrader/exchange wawachief/jupyterhub

et voilà, en modifiant juste la ligne de création du container, vos données sont persistantes ! Vous pouvez effacer le container et en recréer un, vous retrouverez vos données. Vous avez maintenant un serveur opérationnel pour la production.

Méthode : Sauvegarde des données

Dans la commande ci-dessous, nous allons créer un nouveau container basé sur une ubuntu qui va accéder aux volumes de notre container jhub et fabriquer une archive tar qui sera stockée dans le répertoire courant de la machine hôte. L'option --rm permet d'effacer ce container temporaire qui ne sert qu'à la récupération des données.

docker run --rm --volumes-from jhub -v $(pwd):/backup ubuntu tar cvf /backup/backup.tar /home /srv/nbgrader/exchange

docker run --rm --volumes-from jhub -v $(pwd):/backup ubuntu tar cvf /backup/backup.tar /home /srv/nbgrader/exchange

Méthode : Récupération des données

La ligne suivante va restaurer l'archive backup.tar réalisée ci-dessus d'un nouveau container jhub_new que l'on a déjà lancé.

docker run --rm --volumes-from jhub_new -v $(pwd):/backup ubuntu bash -c "cd / && tar xvf /backup/backup.tar"

docker run --rm --volumes-from jhub_new -v $(pwd):/backup ubuntu bash -c "cd / && tar xvf /backup/backup.tar"

Ces deux méthodes montrent donc comment transférer le contenu d'un container à un autre. On peut ainsi migrer facilement une installation jupyterhub sur une autre machine.

Complément : Pour en savoir plus...

Voici quelques liens utiles :

Authentification LDAP - réservé aux spécialistes

jupyterhub peut utiliser les comptes d'une base LDAP. Pour cela, il faut

activer la configuration LDAP dans le fichier jupyterhub_config.py (un modèle de conf est présent, il faudra l'adapter à votre serveur)
installer pam_ldap sur le système

apt-get install -yq --no-install-recommends libnss-ldap libpam-ldap nslcd jupyterhub-ldapauthenticator

modifier les fichiers de conf suivants : /etc/libnss-ldap.conf /etc/ldap/ldap.conf /etc/ldap.secret /etc/pam_ldap.secret