Nakalator CLI

Nakalator est un outil en ligne de commande (CLI) conçu pour faciliter la création de dépôts et l'envoi de fichiers sur la plateforme Nakala

Nakalator permet de :

• Créer un dépôt dans Nakala avec des métadonnées associées en utilisant un fichier YAML ;
• Envoyer des fichiers (par exemple, des images) sur Nakala associés à une donnée spécifique ;
• Créer une collection de données ou rattacher des données à une collection déjà existante dans Nakala.

Il peut être considéré comme une alternative à l'outil Mynkl.

Les avantages de Nakalator sont les suivants :

• Retour utilisateur : Nakalator permet de suivre en temps réel le nombre de fichiers en cours d'envoi dans Nakala ;
• Performances : En fonction de la machine utilisée et de la quantité de fichiers, Nakalator réduit le temps d'envoi des fichiers sur Nakala grâce à une méthode d'envoi multi-threads (goroutines) ;
• Intégrité des données : Tests automatiques effectués après l'envoi des fichiers.
• Post-traitements : Génération d'un rapport (mapping) pour les fichiers envoyés sur Nakala, contenant les identifiants DOI et SHA-1 pour aider, par exemple, à la génération des manifestes .

---

Sommaire

• Installation
• Marche à suivre
• FAQ

Installation

Méthode 1 (recommandée)

1. Installez le CLI via pip dans un environnement virtuel ou non :

# (optionnel :) virtualenv -p python3.9 venv # exemple avec python3.9 mais vous pouvez choisir une autre version python3.10 par exemple
# (optionnel :) source venv/bin/activate 
pip install nakalator

2. Testez l'installation :

nakalator --help

Passer à la section Marche à suivre de Readme pour commencer à utiliser Nakalator.

Méthode 2

1. Clonez le projet (via https ou ssh) :

git clone git@github.com:chartes/Nakalator.git # exemple avec ssh ici
cd Nakalator/

2. (Optionnel) Créez un environnement virtuel avec virtualenv, pyenv, etc. ici avec virtualenv par exemple :

virtualenv -p python3.9 venv # exemple avec python3.9 mais vous pouvez choisir une autre version python3.10 par exemple
source venv/bin/activate

3. Installez le CLI :

pip install -e .

4. Testez l'installation :

nakalator --help

Passer à la section Marche à suivre de Readme pour commencer à utiliser Nakalator.

Méthode 3 (non requis pour les utilisateurs. Concerne uniquement le développement de nakalator)

1. Clonez le projet :

git clone git@github.com:chartes/Nakalator.git
cd Nakalator/

2. Créer un environnement virtuel avec virtualenv, pyenv, etc. ici avec virtualenv par exemple :

virtualenv -p python3.9 venv # exemple avec python3.9 mais vous pouvez choisir une autre version python3.10 par exemple
source venv/bin/activate

3. Installez les dépendances :

pip install -r requirements-dev.txt

3. Puis lancer l'outil pour tester :

python3 nakalator.py --help

Si vous êtes dans le dossier Nakalator/nakalator_workspace :

python3 ../nakalator.py --help

Commandes pour le développement très spécifiques

Warning

Le langage Go est nécessaire pour faire fonctionner les commandes suivantes.

Si et seulement si cela est nécéssaire : pour compiler l'ensemble du projet (build, dist, etc. et hors sources GO) avant la distribution via Pypi depuis Naklator/ :

make build_pkg VERSION_PKG=0.0.1-beta # exemple de version à spécifier 

Si et seulement si cela est nécéssaire : en cas de modification des sources Go, vous devez recompiler le binaire depuis Naklator/ pour Linux et pour MacOS :

sous linux :

make build_go

Cela créé alors un binaire nakala_request.so dans le dossier lib/bridge/

sous MacOS :

make build_go # même commande que pour linux

Cela créé alors un binaire nakala_request.dylib dans le dossier lib/bridge/

Marche à suivre

1. Une fois l'installation effectuée, et lors de la première utilisation de l'outil, commencez par créer votre environnement de travail (nommé nakalator_workspace/) via la commande suivante :

nakalator init

La commande crée un dossier nakalator_workspace/ dans votre répertoire courant. Il s'agit de votre espace de travail privilégié et toutes les commandes Nakalator doivent être exécutées à partir de ce dossier. Ce dossier contiendra :

• les fichiers de configuration temporaires (au format YAML) nécessaires pour l'envoi des données sur Nakala (dossier metadatas/) ;
• les fichiers à envoyer (dossier data/)
• les rapports (mapping) des données envoyées (dossier output/)

Notez également la présence d'un fichier nommé credentials.yml pour renseigner les informations de connexion à Nakala (clés API) en test (https://test.nakala.fr/) ou en production (https://nakala.fr/).

2. Commencer par remplir le fichier credentials.yml avec les informations de connexion à Nakala (clés API). Pour l'instance de test, des clés d'API sont disponibles sur la page d'accueil de l'instance de test de Nakala (https://test.nakala.fr/). Pour l'instance de production Nakala, vous devez disposer d'un compte HumanID auprès d'Huma-Num et effectuer une demande d'accès à Nakala.

3. L'organisation des fichiers de métadonnées YAML et des fichiers à envoyer est cruciale. Le fichier pivot YAML contient les métadonnées de la donnée à envoyer sur Nakala et les liens vers les fichiers à envoyer. Plusieurs cas d'usage sont possibles, les plus courants sont :

• Création d'une donnée sur Nakala (rattachée ou non à une collection existante ou à créer) avec des fichiers associés (par exemple, des images) :

  1. Déposez votre fichier YAML (préalablement rempli) dans le dossier metadatas/ (par exemple metadatas/mon_projet.yml) ;
  2. Déposez vos images dans un dossier spécifique dans data/ (par exemple data/mon_projet/image1.jpg, data/mon_projet/image2.jpg, etc.).

  Voici un exemple de structure de dossiers pour ce cas d'usage :

   nakalator_workspace/
       |
       ├── metadatas/
       │    ├── mon_projet.yml
       │
       ├── data/
            ├── mon_projet/
                 ├── image1.jpg
                 ├── image2.jpg
  

• Création de plusieurs données (envoi en lot) sur Nakala (rattachées ou non à une collection existante ou à créer) avec des fichiers associés (par exemple, des images) pour chacune d'elles :

  1. Déposez vos fichiers YAML (préalablement remplis) dans un sous-dossier situé dans le dossier metadatas/ (par exemple metadatas/mon_projet/mon_projet_1.yml, metadatas/mon_projet/mon_projet_2.yml) ;
  2. Déposez vos images dans des sous-dossiers spécifiques placés dans un sous-dossier (portant le nom du projet) de data/ (par exemple data/mon_projet/mon_projet_1/image1.jpg, data/mon_projet/mon_projet_1/image2.jpg, data/mon_projet/mon_projet_2/image1.jpg, data/mon_projet/mon_projet_2/image2.jpg, etc.).

  Voici un exemple de structure de dossiers pour ce cas d'usage :

    nakalator_workspace/
         |
         ├── metadatas/
         │    ├── mon_projet/
         │         ├── mon_projet_1.yml
         │         ├── mon_projet_2.yml
         │
         ├── data/
                ├── mon_projet/
                  ├── mon_projet_1/
                         ├── image1.jpg
                         ├── image2.jpg
                  ├── mon_projet_2/
                         ├── image1.jpg
                         ├── image2.jpg
  

Tip

Pour remplir le fichier YAML, vous pouvez vous inspirer du fichier metadata_example.yml présent dans le dossier nakalator_workspace/ lors de l'initialisation de l'environnement de travail. Vous remarquerez que certaines informations sont obligatoires et d'autres facultatives. Vous pouvez également consulter le dossier examples/ qui contient des exemples de fichiers de métadonnées inspirés d'autres projets.

Tip

Prévoyez un plan de nommage rigoureux pour les images avant l'envoi, car cela déterminera l'ordre des images dans Nakala.

Tip

Si vous avez plusieurs données à créer, vous pouvez utiliser les suffixes spéciaux _PREV et _NEXT. La donnée avec le suffixe _PREV sera automatiquement placée en première position et celle avec le suffixe _NEXT en dernière position. Cela peut être utile pour les pages liminaires et postliminaires d'un document, par exemple.

Tip

Pour plus d'informations sur les métadonnées Nakala, consultez la documentation Nakala.

4. Une fois l'étape 2 terminée, vous pouvez lancer l'envoi des données sur Nakala depuis le répertoire nakalator_workspace/ :

nakalator main

Suivez les instructions et répondez aux questions posées par le CLI.

Tip

Une fois la donnée créée, il est toujours possible de modifier ou d'ajouter des métadonnées dans l'interface Nakala suivant l'instance désignée (production ou test).

5. À la fin du processus, un ou plusieurs fichiers de mapping seront générés dans le dossier output/ de votre nakalator_workspace/. Le nommage est le suivant :

   • Donnée rattachée à une collection : data_{ordre}_{doi_de_la_collection}_{doi_de_la_donnee}.csv
   • Donnée non rattachée à une collection : data_{ordre}_{doi_de_la_donnee}.csv

Ce fichier, à bien conserver, contient l'ensemble des fichiers envoyés sur Nakala avec les identifiants DOI et SHA-1 associés.

6. Vous pouvez vérifier dans l'interface Nakala que les données ont bien été envoyées :

• Modifier manuellement les métadonnées des données.
• Ajouter des fichiers supplémentaires si nécessaire.
• Si les images ne sont pas triés, utiliser la fonction de tri pour remettre les images dans l'ordre dans Nakala (cf. FAQ pour plus d'informations).
• Passer les données et les collections en mode "publié" (au lieu de "privé").

Warning

Le nombre de données en mode "privé" est limité sur Nakala, pensez à contrôler votre stockage régulièrement et à publier ces données au fur et à mesure surtout si vous avez un grand nombre de données à envoyer.

Warning

Une fois la donnée "publiée" dans Nakala, il n'est plus possible de la supprimer (contactez le support de Nakala).

FAQ

• Comment remettre les images dans l'ordre sur Nakala ?

  Vous pouvez vous rendre sur la page de la donnée créée dans Nakala, utiliser l'icône de tri, puis sauvegarder les modifications.