Installation

CristHAL est une application Python s’appuyant sur le framework Django (https://www.djangoproject.com/). Les composants de l’architecture technique sont illustrés par la Fig. 5.

Fig. 5 Les composants techniques

Tous ces composants sont des logiciels libres qui fonctionnent sur toutes les plateformes.

• Le cœur du système est une application Python/Django.

• Le stockage des données est assuré par MySQL (http://mysql.com).

• Un moteur de recherche, ElasticSearch (https://www.elastic.co/fr/elasticsearch/), est utilisé pour la procédure d’appariement.

• Enfin un serveur Web quelconque, doté d’une passerelle WSGI, est requis pour une mise en production.

Pour une installation initiale, il n’est pas nécessaire de disposer d’un serveur Web: un serveur intégré à Django permet d’effectuer la configuration et les tests, ce que nous appelons « mise en route » dans ce qui suit. Pour une mise en production, un vrai serveur web s’impose, ainsi que quelques précautions de configuration.

À l’exception (très relative) d’ElasticSearch, cette architecture est très classique et utilisé par des millions de sites web. On trouve donc de très nombreuses ressources pour la configuration des différents compsosants. Ce qui suit se concentre donc sur la partie spécifique à CristHAL.

Mise en route

On suppose donc que vous disposez d’une machine équipée de Python (version au moins 3.6), et d’un accès à un serveur MySQL et à un serveur ElasticSearch.

MySQL

Pour MySQL il est nécessaire de créer une base et deux comptes

• un compte administrateur disposant de tous les droits sur la base

• un compte ne disposant que des droits de lecture ; ce deuxième compte est utilisé pour exécuter des requêtes SQL saisies dans un formulaire: mieux vaut éviter les fausses manœuvres.

Voici des exemples de commandes (elles se trouvent dans install/creationDb.sql).

 /* Nom de base à reporter dans cristhal/local_settings.py */
 create database cristhal CHARACTER SET utf8;

 /*
 * Nom admin et mot de passe à changer et reporter dans cristhal/local_settings.py
 */
 grant all privileges on cristhal.* to cristhalAdmin identified by 'mdpCristhal';

/* Compte avec droits de lecture uniquement, pour les requêtes SQL */
 grant select on cristhal.* to cristhalLecteur identified by 'mdpLecteur';

Important

Ne les copiez pas telles quelles ! Changez au moins le mot de passe

ElasticSearch

Par défaut le compte d’accès à ElasticSearch est elastic/changeme. Il vaut effectivement mieux le changer. L’utilitaire de changement du mot de passe est dans le répertoire elasticsearch/bin:

elasticsearch-setup-passwords interactive

Pas besoin de créer l’index pour ElasticSearch, CristHAL s’en charge à la première connexion.

CristHAL

Le code de CristHAL peut être récupéré sur https://github.com/cedric-cnam/cristhal. Installez-le dans un répertoire que nous appelerons cristhaldir.

Note

Dans tout ce qui suit, python et pip s’appliquent à Python3, et correspondent dans certains environnements aux commandes python3 et pip3.

La première chose à faire est d’installer les modules Python nécessaires à CristHAL. Ils sont énumérés dans le fichier requirements.txt.

pip3 install -r requirements.txt

On peut passer à la configuration des accès serveurs.

Accès MySQL et ElasticSearch

Les accès aux serveurs sont configurés dans des fichiers du répertoire cristhaldir/cristhal. La configuration générale est dans le fichier settings.py, la configuration spécifique à un site doit être placée dans un fichier local_settngs.py dont les options prennent priorité sur le premier.

Dans cristhaldir/cristhal, copiez local_settings_exemple.py en local_settings.py. Puis éditez ce dernier.

La configuration d’accès au serveur MySQL est indiquée dans la variable DATABASES. Reportez-y vos paramètres de site.

  DATABASES = {
      'default': {
          'ENGINE': 'django.db.backends.mysql',
          'NAME': 'nom_bd_locale',
          'USER': 'admin_bd_locale',
          'PASSWORD': 'mdp_bd_locale',
          'HOST': '127.0.0.1',
          'PORT': '3306',
          'OPTIONS': {
              'sql_mode': 'STRICT_ALL_TABLES',
          },
      },
  'lecteur': {
      'ENGINE': 'django.db.backends.mysql',
      'OPTIONS': {
      'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
      },
      'NAME': 'cristhal',
      'USER': 'cristhalLecteur',
      'PASSWORD': 'mdpLecteur',
      'HOST': '127.0.0.1',
      'PORT': '3306',
  }
}

Note

Il faut définir deux connexions, une pour l’administrateur, et l’autre pour le compte “lecteur”. Ne changez pas les noms des connexions.

La configuration d’accès au serveur ElasticSearch est indiquée dans les variables suivantes. Vous pouvez conserver la valeur de ES_INDEX_REF si vous le souhaitez. Indiquez les autres paramètres dans le dictionnaire ELASTIC_SEARCH.

ES_INDEX_REF = "cristhal"
ELASTIC_SEARCH = {"host": "localhost", "port": 9200,
            "index": ES_INDEX_REF,
            "auth_login": "elastic",
             "auth_password": "changeme"
            }

Reportez bien sûr le login et mot de passe d’accès au serveur ElasticSearch.

Certains fichiers (les CSV des sources du référentiel notamment) sont stockés dans un répertoire local spécifié par le paramètre MEDIA_ROOT. Par défaut, ce répertoire se nomme “media” et il se trouve dans cristhaldir.

MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

Il est préférerable d’indiquer un répertoire distinct de l’application. Dans tous les cas, le compte utilisateur sous lequel l’application s’exécute doit avoir le droit d’y écrire.

Un dernier paramètre à régler est l’emplacement des fichiers journaux. Le chemin proposé par défaut est:

LOG_DIR = '/var/log'

Indiquez le chemin qui convient (et vérifiez qu’il est possible d’écrire dans ce répertoire pour le processus qui exécute CristHAL).

Création du schéma et initialisation

Si votre configuration est correcte, vous devez pouvoir exécuter la commande suivante dans cristhaldir.

python manage.py migrate

C’est une commande Django qui crée (ou modifie) le schéma. Si la connexion au serveur MySQL échoue, vous le saurez tout de suite. Sinon, votre schéma est créé.

C’est presque prêt! Maintenant ajoutez un super-utilisateur avec une autre commande Django.

python manage.py createsuperuser

Suiviez les instructions (et mémorisez le compte !). Pour finir, CristHAL propose une autre commande pour créer une configuration initiale.

python manage.py init_publis

Quelques messages vous indiquent les opérations effectuées.

Il ne reste qu’à lancer le serveur intégré à Django.

python manage.py runserver

Pas d’erreur ? Alors vous pouvez accèder avec un navigateur quelconque à http://localhost:8000 et vous devriez obtenir l’écran de la Fig. 6 (qui peut évoluer avec les versions).

Fig. 6 L’écran d’accueil

Vous pouvez vous connecter avec le compte super-utilisateur défini précédemment. Tout est prêt pour commencer à utiliser l’application (en mode “tests”: pour la mise en production voir ci-dessous). Commençons par l’interface d’administration.

L’interface d’administration

Une fois connecté avec un compte d’administration, un menu Admin apparaît (Fig. 6).

Fig. 7 L’écran d’accueil après connexion

Ce menu donne accès aux fonctions de création et de mise à jour des principaux objets configurant CristHAL: utilisateurs, codification, collections, sources (du référentiel, etc.)

La création des groupes (définissant des droits d’accès) et des utilisateurs est une fonction standard de Django. Vous pouvez créer quelques utilisateurs: seuls ceux dotés du droit “super-utilisateur” pourront accéder au menu d’administration.

Les autres formulaires sont gérés automatiquement par Django, mais donnent accès aux données spécifiques. Pour vous rôder vous pouvez accéder à l’interface de définition des configurations.

Il doit exister au moins une configuration, nommée défaut. Elle est créée à l’initialisation de CristHAL et contient plusieurs paramètres:

• l’adresse des services web HAL (ne pas modifier en principe);

• La période (année min et max) de récolte des publications;

• les types de publication HAL qui doivent être importés dans le système ; par défaut des types comme “AUTRE”, “POSTER” ou “RAPPORT” ne sont pas importés;

• le répertoire d’export ; il doit s’agit d’un répertoire existant sur la machine du serveur web, dans lequel ce même serveur a le droit d’écrire (par défaut: /tmp)

Fig. 8 Le formulaire de configuration

Au-delà de la configuration initiale qui implique quelques éditions de fichier, tout le paramétrage de CristHAL se fait via cette interface d’administration.

Important

Pour revenir au site principal à partir de l’interface d’administration, il faut suivre le lien “View site” en haut à droite.

Mise en production

Pour une mise en production, il faut associer CristHAL à un serveur Web, et changer un peu la configuration.

Le serveur web

CristHAL est une application Django standard, et l’association avec un serveur ne présente aucune spécificité. Dans le répertoire cristhaldir/cristhal se trouve un fichier wsgi.py qui sert à créer une passerelle WSGI avec un serveur comme Apache, Nginx ou Gunicorn.

La documentation explique en détail la procédure pour ces différents serveurs: https://docs.djangoproject.com/fr/3.2/howto/deployment/wsgi/.

Configuration en production

Il faut évidemment adapter la configuration pour s’assurer de la protection de l’application si elle est exposée sur le Web. Là encore, la documentation https://docs.djangoproject.com/en/3.2/howto/deployment/checklist/ nous dit l’essentiel, et on trouve de très nombreux tutoriels qui détaillent les précautions à prendre.

La configuration de CristHAL peut se placer dans le fichier local_settings.py (vous pouvez en créer un spécifique à l’environnement de production). Voici quelques modifications essentielles. La première chose à faire est de quitter le mode debug.

Debug = False

Ajouter également une clé secrète. Une bonne pratique est de la définir comme variable d’environnement et de la paramétrer ainsi.

SECRET_KEY = os.environ['SECRET_KEY']

Enfin il faut spécifier les domaines servis par l’application dans le tableau suivant.

ALLOWED_HOSTS = []