From ef4b05975c4532b6b1f5107bb5c130cbd0f65536 Mon Sep 17 00:00:00 2001 From: Alice BRENON <alice.brenon@ens-lyon.fr> Date: Mon, 10 Oct 2022 17:28:51 +0200 Subject: [PATCH] Add install instructions for Docker and guix in README + the source Dockerfile --- Dockerfile | 6 +++ README.md | 108 +++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 94 insertions(+), 20 deletions(-) create mode 100644 Dockerfile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..1917d37 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,6 @@ +FROM geoparsing-tutorial:latest +EXPOSE 8888 +WORKDIR /srv/notebooks +CMD ln -s /bin/python3 /bin/python +CMD ln -s /bin/pip3 /bin/pip +ENTRYPOINT ["/bin/jupyter-notebook", "--allow-root", "--ip", "0.0.0.0"] diff --git a/README.md b/README.md index 6f268c9..34dad40 100644 --- a/README.md +++ b/README.md @@ -2,33 +2,37 @@ # Tutoriel - ANF TDM 2022 Python Geoparsing - Supports pour l'atelier [Librairies Python et Services Web pour la reconnaissance d’entités nommées et la résolution de toponymes](https://anf-tdm-2022.sciencesconf.org/resource/page/id/11) de la formation CNRS [ANF TDM 2022](https://anf-tdm-2022.sciencesconf.org). - - Dans ce tutoriel, nous montrons comment utiliser des librairies Python pour la reconnaissance des entités nommées (*Named Entity Recognition*) et pour la résolution de toponymes (*Geocoding*). Pour cela, nous utiliserons les librairies ([spaCy](https://spacy.io), [Stanza](https://stanfordnlp.github.io/stanza/index.html)) et [Perdido](https://github.com/ludovicmoncla/perdido). Nous expérimenterons et comparerons ces librairies au travers deux études de cas : le traitement d'articles encyclopédiques (corpus issu du projet [GEODE](https://geode-project.github.io)) et le traitement de descriptions de randonnées (corpus issu du projet [ANR CHOUCAS](http://choucas.ign.fr)). - - - **Animateurs**: [Ludovic Moncla](https://ludovicmoncla.github.io) (INSA Lyon) et [Alice Brenon](https://perso.liris.cnrs.fr/abrenon/) (CNRS / INSA Lyon) - -### Tâches et problématiques abordées +## Tâches et problématiques abordées 1. Reconnaissance et classification des entités nommées en français 2. Résolution de toponymes (problématique de désambiguïsation) 3. Créer et afficher une carte à partir d'un texte +## Comment exécuter ce notebook + +- en [cloud](#sur-le-cloud) +- en local + + avec [conda](#avec-conda) + + avec [docker](#avec-docker) + + avec [guix](#avec-guix) + +### Sur le «cloud» Vous pouvez exécuter le notebook à distance en utilisant [](http://colab.research.google.com/) ou [](https://mybinder.org/v2/git/https%3A%2F%2Fgitlab.liris.cnrs.fr%2Flmoncla%2Ftutoriel-anf-tdm-2022-python-geoparsing.git/HEAD?labpath=Tutoriel-geoparsing.ipynb). Sinon, pour exécuter ce tutoriel depuis un environnement local sur votre ordinateur, vous pouvez suivre les instructions ci-dessous. -## Installer conda +### Installer en local + +#### Avec conda [Conda](https://conda.io/projects/conda/en/latest/index.html) est un système de gestion de paquets et d'environnement open source. Il installe, exécute et met à jour rapidement les paquets et leurs dépendances. Nous l'utiliserons pour gérer l'environnement python et toutes les bibliothèques python nécessaires pour les tutoriels. @@ -37,26 +41,23 @@ Il existe plusieurs façons d'installer conda sur votre ordinateur : 2. [Miniconda](https://docs.conda.io/en/latest/miniconda.html): une installation minimale pour conda, sans application graphique 3. [Miniforge](https://github.com/conda-forge/miniforge): une autre installation minimale pour conda, sans application graphique (recommandée pour les puces Mac ARM M1 ou M2 (Apple Silicon)) - -## Configurer un environnement conda - -### Cloner ce dépôt git +##### Clôner ce dépôt git ```bash git clone https://gitlab.liris.cnrs.fr/lmoncla/tutoriel-anf-tdm-2022-python-geoparsing.git ``` -### Configurer l'environnement avec toutes les dépendances nécessaires +##### Configurer l'environnement avec toutes les dépendances nécessaires -#### Méthode 1 +###### Méthode 1 -* Uilisateurs MacOS/Linux : Créer un nouvel environnement nommé `tdm-geoparsing-py39` avec toutes les dépendances nécessaire en utilisant le fichier de configuration `environment-osx-linux.yml` : +* Uilisateurs MacOS/Linux : Créer un nouvel environnement nommé `tdm-geoparsing-py39` avec toutes les dépendances nécessaires en utilisant le fichier de configuration `environment-osx-linux.yml` : ```bash conda env create -f environment-osx-linux.yml ``` -* Uilisateurs Windows : Créer un nouvel environnement nommé `tdm-geoparsing-py39` avec toutes les dépendances nécessaire en utilisant le fichier de configuration `environment-win64.yml` : +* Uilisateurs Windows : Créer un nouvel environnement nommé `tdm-geoparsing-py39` avec toutes les dépendances nécessaires en utilisant le fichier de configuration `environment-win64.yml` : ```bash conda env create -f environment-win64.yml @@ -68,8 +69,7 @@ conda env create -f environment-win64.yml conda activate tdm-geoparsing-py39 ``` - -#### Méthode 2 +###### Méthode 2 * Créer un nouvel environnement nommé `tdm-geoparsing-py39` @@ -95,14 +95,82 @@ conda install fiona==1.8.21 pip install -r requirements.txt ``` - ### Lancer le serveur Jupyter ```bash jupyter notebook ``` +### Avec Docker + +Vous pouvez directement démarrer un conteneur avec le tutoriel et toutes ses +dépendances en tappant: + +```bash +docker run -p 8888:8888 --rm geodeproject/geoparsing-tutorial:latest +``` + +Le serveur `jupyter`, tournant à l'intérieur du conteneur, ne pourra pas ouvrir +votre navigateur automatiquement mais vous pouvez y accéder normalement en +suivant les instructions qui s'affichent alors dans le terminal au démarrage du +serveur. +### Avec Guix +Si le gestionnaire de paquet [`guix`](https://guix.gnu.org/) est installé sur +votre machine, vous pouvez démarrer directement un environnement de travail +depuis le [channel](https://gitlab.liris.cnrs.fr/geode/geode-packages) du projet +[GÉODE](https://geode-project.github.io/). +En supposant que vous vous trouvez dans une copie du channel (pas du présent +dépôt contenant le tutoriel, il n'est pas nécessaire si vous utilisez `guix`), +vous pouvez démarrer un conteneur semblable à celui accessible via `docker` avec +la commande suivante: +```bash +guix shell --container --network -L . geoparsing-tutorial -- /bin/sh -c 'jupyter-notebook $GUIX_ENVIRONMENT/srv/notebooks' +``` +#### Comment modifier ce tutoriel + +C'est également avec `guix` qu'a été généré le conteneur +[`docker`](#avec-docker) ci-dessus. Les étapes suivantes peuvent constituer une +base de travail si vous avez besoin de régénérer un conteneur intégrant des +modifications de ce dépôt. Elles s'exécutent aussi dans une copie locale du +channel du projet (ou bien alors il faut remplacer l'argument `.` — dossier +courant — de l'option `-L` par le chemin vers cette copie ou avoir ajouté le +channel du projet à la liste des channels connus par guix — fichier +[`channels.scm`](https://guix.gnu.org/fr/manual/devel/en/html_node/Using-a-Custom-Guix-Channel.html#Using-a-Custom-Guix-Channel)) + +##### Re-calculer une image de base pour le conteneur + +(cette étape est optionnelle car incluse dans la suivante mais elle prend du +temps et il peut être rassurant de la voir s'exécuter directement dans le +shell, bien que seul le chemin affiché à la fin de l'opération soit nécessaire à +l'étape suivante) + +```bash +guix pack -f docker -L . -S /bin=bin -S /srv=srv geoparsing-tutorial +``` + +#### Import de cette image dans docker + +Si vous avez exécuté l'étape précédent, vous pouvez remplacer directement la +sous-commande `$(…)` par la sortie en `/gnu/store/.*.tar.gz` qui s'est +normalement affiché (mais la réexécuter ne posera pas de soucis, et `guix` ne +refera pas deux fois le travail). + +```bash +docker load < $(guix pack -f docker -L . -S /bin=bin -S /srv=srv geoparsing-tutorial) +``` + +#### Finaliser l'image + +À partir de cette couche de base nommée automatiquement +`geoparsing-tutorial:latest`, le conteneur définitif est généré en suivant le +Dockerfile présent dans ce dépôt (vous devez donc revenir dans une copie locale +de ce dépôt contenant le tutoriel et le fichier `Dockerfile` pour cette dernière +étape). + +```bash +docker build -f Dockerfile . +``` -- GitLab