Configuration docker pour déployer le portail national des thÚses dont le but est de donner accàs à toutes les theses de theses.fr à l'ensemble de l'enseignement supérieur et de la recherche. Ces configurations visent à permettre un déploiement uniforme en local sur la machine d'un développeur, et sur les serveurs de dev, test, et prod.
Les URLs temporaires du futur theses.fr sont les suivantes :
- en préprod :
- https://v2-prod.theses.fr : la homepage de theses.fr
- https://v2-prod.theses.fr/api/v1/recherche-java/completion/?q=n%C3%A9olithique : l'API de recherche par les theses de theses.fr
- https://v2-prod.theses.fr/api/v1/personnes/completion/?q=erwann : l'API de recherche par les personnes de theses.fr
- https://v2-prod.theses.fr/poc-fede/ : le PoC de fédération d'identités
- https://v2-prod.theses.fr/kibana/ : le kibana backoffice de theses.fr
- en test :
- https://v2-test.theses.fr : la homepage de theses.fr
- https://v2-test.theses.fr/api/v1/recherche-java/completion/?q=n%C3%A9olithique : l'API de recherche par les theses de theses.fr
- https://v2-test.theses.fr/api/v1/personnes/completion/?q=erwann : l'API de recherche par les personnes de theses.fr
- https://v2-test.theses.fr/kibana/ : le kibana backoffice de theses.fr
- en dev :
- https://v2-dev.theses.fr : la homepage de theses.fr
- https://v2-dev.theses.fr/api/v1/recherche-java/completion/?q=n%C3%A9olithique : l'API de recherche par les theses de theses.fr
- https://v2-dev.theses.fr/api/v1/personnes/completion/?q=erwann : l'API de recherche par les personnes de theses.fr
- https://v2-dev.theses.fr/kibana/ : le kibana backoffice de theses.fr
- en local : (fonctionne uniquement si vous avez une intallation de theses.fr avec cette configuration)
- https://v2-local.theses.fr : la homepage de theses.fr
- https://v2-local.theses.fr/api/v1/recherche-java/completion/?q=n%C3%A9olithique : l'API de recherche par les theses de theses.fr
- https://v2-local.theses.fr/api/v1/personnes/completion/?q=erwann : l'API de recherche par les personnes de theses.fr
- https://v2-local.theses.fr/poc-fede/ : le PoC de fédération d'identités
- https://v2-local.theses.fr/kibana/ : le kibana backoffice de theses.fr
- docker
- docker compose
- réglages
vm.max_map_count
pour elasticsearch (cf FAQ pour les détails du réglage)
On commence par récupérer la configuration du déploiement depuis le github :
cd /opt/pod/ # à adapter en local car vous pouvez cloner le dépà t dans votre homedir
git clone https://github.com/abes-esr/theses-docker.git
Ensuite on configure notre déploiement en prenant exemple sur le fichier .env-dist
qui contient toutes les variables utilisables avec les explications :
cd /opt/pod/theses-docker/
cp .env-dist .env
# personnalisez alors le .env en partant des valeurs exemple présentes dans le .env-dist
# pour un déploiement en local, vous n'avez pas besoin de personnaliser le .env
Finalement on rÚgle quelques droits sur les répertoires et on peut démarrer l'application :
# forcer les droits max pour les volumes déportés sur le systà me de fichier local
cd /opt/pod/theses-docker/
mkdir -p volumes/theses-elasticsearch/ && chmod 777 volumes/theses-elasticsearch/
mkdir -p volumes/theses-elasticsearch-tmp/ && chmod 777 volumes/theses-elasticsearch-tmp/
mkdir -p volumes/theses-elasticsearch-setupcerts/ && chmod 777 volumes/theses-elasticsearch-setupcerts/
mkdir -p volumes/theses-kibana/ && chmod 777 volumes/theses-kibana/
# puis démarrer l'application
cd /opt/pod/theses-docker/
docker compose up -d
A partir de cet instant l'application Ă©coutera sur l'IP du serveur et sera accessible sur les URL suivantes (remplacer 127.0.0.1 par le nom du serveur) :
- http://127.0.0.1:10301/ : pour la homepage de theses.fr (
theses-front
) - http://127.0.0.1:10301/api/v1/recherche/_search : pour l'api de recherche de theses.fr (
theses-api-recherche
) - http://127.0.0.1:10301/poc-fede/ : pour le PoC de fédération d'identités (attention, suivre [cette doc]](./README.faq.md) pour un fonctionnement en local)
- http://127.0.0.1:10301/kibana/ : le kibana backoffice de theses.fr
Voir aussi :
Pour la prod il est nécessaire de dérouler une installation classique (cf section au dessus) puis de réaliser quelques opérations listées ci-dessous :
- Il est nécessaire de générer des certificats auto-signés pour enregistrer theses.fr comme fournisseur de service dans la fédération d'identités Education-Recherche.
- Et il est nécessaire de configurer elasticsearch de theses.fr avec 3 noeuds minimum, cf la doc pour configurer theses.fr avec un cluster elasticsearch à plusieurs noeuds
Pour démarrer l'application :
cd /opt/pod/theses-docker/
docker compose up
# ajouter -d si vous souhaitez démarrer l'application en tache de fond
# dans le cas contraire, utilisez CTRL+C pour ensuite quitter l'application
Pour arrĂȘter l'application PROPREMENT voir chapitre Mise Ă Jour ci aprĂšs Sinon dans l'urgence ou s'il n'y a pas d'activitĂ©:
cd /opt/pod/theses-docker/
docker compose stop
Pour vérifier que l'application est démarrée, on peut consulter l'état des conteneurs :
cd /opt/pod/theses-docker/
docker compose ps
# doit retourner quelque chose comme ceci :
#19:12 $ docker compose ps
# Name Command State Ports
#--------------------------------------------------------------------------------------------------------------
#theses-docker_theses-api-diffusion_1 httpd-foreground Up 80/tcp
#theses-docker_theses-rp_1 httpd-foreground Up 0.0.0.0:443->443/tcp,:::443->443/tcp, 80/tcp
Pour vérifier que l'application est bien lancée, on peut aussi consulter ses logs :
cd /opt/pod/theses-docker/
docker compose logs --tail=50 -f
Les logs de tous les conteneurs de theses-docker sont reversés dans le puits de log de l'Abes. Voici un exemple de ces logs :
Les objectifs des déploiements continus de theses-docker sont les suivants (cf poldev) :
- git push sur la branche
develop
provoque un déploiement automatique sur le serveurdiplotaxis1-dev
- git push (le plus couramment merge) sur la branche
main
provoque un déploiement automatique sur le serveurdiplotaxis1-test
- git tag X.X.X (associé à une release) sur la branche
main
permet un déploiement (non automatique) sur le serveurdiplotaxis1-prod
Le déploiement automatiquement de theses-docker
utilise l'outil watchtower. Pour permettre ce déploiement automatique avec watchtower, il suffit de positionner à false
la variable suivante dans le fichier /opt/pod/theses-docker/.env
:
THESES_WATCHTOWER_RUN_ONCE=false
Le fonctionnement de watchtower est de surveiller réguliÚrement l'éventuelle présence d'une nouvelle image docker de theses-front
et theses-...
, si oui, de rĂ©cupĂ©rer l'image en question, de stopper le ou les les vieux conteneurs et de crĂ©er le ou les conteneurs correspondants en rĂ©utilisant les mĂȘmes paramĂštres que ceux des vieux conteneurs. Pour le dĂ©veloppeur, il lui suffit de faire un git commit+push par exemple sur la branche develop
d'attendre que la github action build et publie l'image, puis que watchtower prenne la main pour que la modification soit disponible sur l'environnement cible, par exemple sur la machine diplotaxis1-dev
.
Le fait de passer THESES_WATCHTOWER_RUN_ONCE
Ă false
va faire en sorte d'exécuter périodiquement watchtower. Par défaut cette variable est à true
car ce n'est pas utile voir cela peut générer du bruit dans le cas d'un déploiement sur un PC en local.
Cette section explique comment préparer la belle URL publique https://theses.fr finale ou aussi les URL temporaires de type https://v2-dev.theses.fr/ au niveau de l'infra Abes.
Il est nécessaire de configurer une entrée DNS pointant associant theses.fr
ou v2-dev.theses.fr
(pour ne prendre que cet exemple) Ă l'IP (ou au CNAME) du reverse proxy de l'Abes.
Ensuite il faut ajouter un VirtualHost au niveau du reverse proxy (à adapter en fonction des noms de domaines à gérer) :
# redirection automatique http vers https
<VirtualHost *:80>
ServerName v2-dev.theses.fr
ServerAdmin admin@theses.fr
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/(.*|$) https://%{HTTP_HOST}/$1 [L,R]
</VirtualHost>
<VirtualHost *:443>
ServerName v2-dev.theses.fr
ServerAdmin admin@theses.fr
RewriteEngine on
ErrorLog logs/theses-docker-test-error_log
CustomLog logs/theses-docker-test-access_log common
TransferLog logs/ssl_access_log
LogLevel warn rewrite:trace3
SSLEngine on
SSLProxyEngine on
SSLCertificateFile /etc/pki/tls/certs/__abes_fr_cert.cer
SSLCertificateKeyFile /etc/pki/tls/private/abes.fr.key
SSLCertificateChainFile /etc/pki/tls/certs/__abes_fr_interm.cer
# ne vérifie pas le certificat interne de theses-rp
# car ce dernier est auto-signé
# https://httpd.apache.org/docs/2.4/fr/mod/mod_ssl.html#sslproxyverify
SSLProxyVerify none
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLProxyCheckPeerExpire off
# proxification de theses-rp qui écoute par défaut sur le port 10300
# et dans cet exemple qui est hébergé sur le serveur diplotaxis2-dev
ProxyPreserveHost On
ProxyPass "/" "https://diplotaxis2-dev.v212.abes.fr:10300/"
ProxyPassReverse "/" "https://diplotaxis2-dev.v212.abes.fr:10300/"
</VirtualHost>
Pour sauvegarder l'application, il faut :
- Sauvegarder la base de données (base Oracle sur les serveurs orpin) : TODO préciser de quel schéma et de quelles tables on parle
- Sauvegarder le fichier
/opt/pod/theses-docker/.env
qui est un fichier non versionné et qui permet de configurer tous les conteneurs docker de l'appli - Sauvegarder les certificats auto-signés présents dans le répertoire
/opt/pod/theses-docker/volumes/theses-rp/shibboleth/ssl/
(ces certificats permettent Ă theses.fr d'ĂȘtre reconnu par la fĂ©dĂ©ration d'identitĂ©s Education-Recherche) - Sauvegarder le dump elasticsearch et/ou le paramĂ©trage kibana : Il faut, via Kibana, programmer des sauvegardes (appellĂ©es 'snapshots') sur un volume externe NFS par ex. prĂ©alablement configurĂ© et montĂ© dans un volume local Ă l'application. On passe par le menu Management -> snapshot and restore et on choisit les donnĂ©es et la frĂ©quence des sauvegardes.
- Sauvegarder les certificats elasticsearch : todo vraiement nécessaire ? et todo expliquer comment faire ?
Les chemins volumineux Ă d'exclure des sauvegardes sont les suivants :
/opt/pod/theses-docker/volumes/theses-elasticsearch/*
: car il contient les données binaires d'elasticsearch
Pour restaurer l'application, il faut selon la gravité de la situation :
- Simple restauration d'index depuis un snapshot : Dans le menu Kibana de gestion des index il faut cloturer l'index à restaurer. Puis aller sur Management -> snapshot and restore et choisir (cocher à gauche) le snapshot à la bonne date. Lancer la restauration (icone en fin de ligne) : une suite de pages permets ensuite de choisir quels paramÚtres seront restaurés. Pour un index seul décocher tout et garder seulement l'index voulu.
- Restauration complĂšte depuis un snapshot : mĂȘme principe mais choisir tous les index et bien vĂ©rifier les paramĂštres globaux Ă restaurer - ou pas.
- Restaureration de la base de données : procédure de restauration propre à Oracle DB (rman)
- Réinstallation de l'application : Cf. plus haut la section 'Installation' en réutilisant le
.env
précédement sauvegardé.
Se référer au code de https://github.com/abes-esr/theses-batch-indexation/tree/11theses (branche 11theses)
Ce batch s'exécute au démarrage de theses-docker et va charger des thÚses et des personnes dans les indexes suivants :
- theses-sample
- personnes-sample
Cet échantillon de données permet de démarrer theses-docker et de le tester en étant totalement indépendant du SI de l'Abes.
Remarque : l'index sample des personnes n'est pas encore fonctionnel Ă la date du 03/07/2023
- Arret propre du cluster
- Soit via la console Devtool dans Kibana :
PUT _cluster/settings
{
"persistent": {
"cluster.routing.allocation.enable": "primaries"
}
}
POST /_flush
- Soit avec Curl si la console n'est pas disponible :
curl -k -v -u elastic:<snip> -XPUT "http://diplotaxis1-dev.v212.abes.fr:10302/_cluster/settings" -H "kbn-xsrf: reporting" -H "Content-Type: application/json" -d'
{
"persistent": {
"cluster.routing.allocation.enable": "primaries"
}
}'
# Flush
curl -XPOST "http://diplotaxis1-dev.v212.abes.fr:10302/_flush" -H "kbn-xsrf: reporting"
-
Stopper un par un les noeuds data puis finir par les master.
-
Pour une mise Ă jour des produits elastic.co : modifier la version de l'image dans le .env
-
Redémarrer le cluster elasticsearch noeud aprÚs noeud en commencant par les noeux data et en finissant par le(s) master ATTENTION de bien vérifier que le cluster est en statut green ou yellow avant de redémarrer un autre noeud cela peut prendre plusieurs minutes par noeud selon la quantité de données présentes
-
Remettre le cluster en mode actif (uniquement s'il est en statut 'yellow' ou 'green')
- Si Kibana est actif (normalement non aprĂšs une mise Ă jour) par la console Devtool :
GET _cat/nodes
PUT _cluster/settings
{
"persistent": {
"cluster.routing.allocation.enable": null
}
}
# check cluster health
GET _cat/health
- Si Kibana n'est pas démarré (ou ne migre pas suite à une mise à jour - voir les logs) avec Curl :
[.kibana] Action failed with '[incompatible_cluster_routing_allocation] Incompatible Elasticsearch cluster settings detected. Remove the persistent and transient Elasticsearch cluster setting 'cluster.routing.allocation.enable' or set it to a value of 'all' to allow migrations to proceed. Refer to https://www.elastic.co/guide/en/kibana/8.7/resolve-migrations-failures.html#routing-allocation-disabled for more information on how to resolve the issue.
curl -k -v -u elastic:<snip> -XPUT "https://diplotaxis1-dev.v212.abes.fr:10302/_cluster/settings" -d -H 'Content-Type: application/json' '{
"transient": {
"cluster.routing.allocation.enable": null
},
"persistent": {
"cluster.routing.allocation.enable": null
}
}'
Se référer au code de https://github.com/abes-esr/theses-batch-indexation
Le batch peu ĂȘtre utilisĂ© pour :
- Indexer toutes les thÚses depuis la base de données (base oracle THESES) (3h)
- Indexer toutes les personnes présentes dans toutes les thÚses (idem, depuis la base de données oracle) (5h)
Il faut choisir le job en l'indiquant dans spring.batch.job.names:
- indexationThesesDansES
- indexationPersonnesDansES
Puis lancer en ligne de commande : En changeant la valeur de -Dspring.batch.job.names si besoin.
docker exec -it theses-batch-indexation ./jdk-11.0.2/bin/java -Dspring.batch.job.names=indexationThesesDansES -jar theses-batch-indexation-0.0.1-SNAPSHOT.jar > log.txt
Pour le job qui indexe les personnes (indexationPersonnesDansES), il y a une premiÚre étape qui construit le json en base de données, dans la table PERSONNE_CACHE. Cette table n'est pas créée par le batch, si elle n'existe pas les informations pour créer la créer sont dans src/main/resources/personne_cache_table. Dans une seconde étape, on va envoyer le contenu de PERSONNE_CACHE dans Elastic Search.
Il y a un job qui peut faire uniquement cette derniĂšre Ă©tape (1h):
- indexationPersonnesDeBddVersES
docker exec -it theses-batch-indexation ./jdk-11.0.2/bin/java -Dspring.batch.job.names=indexationPersonnesDeBddVersES -jar theses-batch-indexation-0.0.1-SNAPSHOT.jar > log.txt
Il est judicieux de l'utiliser quand on vient d'indexer toutes les personnes dans un environnement, et qu'on souhaite indexer sur un ou plusieurs autres environnements.
Voici la liste et la description des conteneurs déployés par le [docker compose.yml](https://github.com/abes-esr/theses-docker/blob/develop/docker compose.yml)
theses-rp
: conteneur servant de reverse proxy dédié à l'authentification des utilisateurs souhaitant accéder à des thÚses en accÚs restreint. Cette authentification est déléguée à la fédération d'identités Education-Recherche. Ce conteneur est l'instanciation de l'image docker docker-shibboleth-renater-sp.theses-api-diffusion
: conteneur qui sera chargé de l'API (en Java Spring) de theses.fr (travail en cours). Dans le cadre du PoC fédé, ce conteneur est chargé de mettre à disposition un PDF en passant par la fédé.theses-api-recherche
: conteneur qui sera chargé de mettre à disposition l'API de recherche qui sera utilisée par letheses-front
. Cette API fait le passe plat avec le conteneurtheses-elasticsearch
qui contient les donnĂ©es indexĂ©e et recherchables dans le langage de requĂȘtage d'elasticsearch.theses-api-indexation
: conteneur qui sera chargé de proposer une API pour pouvoir indexer une thÚses à l'unité danstheses-elasticsearch
theses-front
: conteneur qui sera chargé du front (en VueJS) de theses.fr (travail en cours)theses-batch
: conteneur qui sera chargé des batchs ponctuels ou périodiques de theses.fr et en particulier d'un batch qui permettra d'indexer en masse les 500 000 thÚses danstheses-elasticsearch
theses-elasticsearch
: conteneur qui sera chargĂ© d'instancier le moteur de recherche elasticsearch qui contiendra l'indexation des TEF de theses.fr et qui mettra Ă disposition le langage de requĂȘtage d'elasticsearch avec l'API d'elasticsearch (non exposĂ© sur internet)theses-kibana
: conteneur qui sera chargé du backoffice detheses-elasticsearch
en proposant des tableaux visuels
Les images docker de theses.fr sont générées à partir des codes open sources disponibles ici :
- https://github.com/abes-esr/docker-shibboleth-renater-sp (pour l'authentification avec la fédération d'identités)
- https://github.com/abes-esr/theses-api-diffusion
- https://github.com/abes-esr/theses-api-recherche
- https://github.com/abes-esr/theses-api-indexation
- https://github.com/abes-esr/theses-front
- https://github.com/abes-esr/theses-batch