proj-esup-grouper

Raccourcis espace

Arborescence des pages

Contexte de cette documentation

On se place ici dans le cadre d'un établissement qui fonctionne avec la version 2.3 de Grouper et qui souhaite opérer une mise à jour de celui-ci.

Apports de Grouper 5.x par rapport à  la 2.3

Par rapport à la version 2.3 que l'on avait documentée en 2017, la dernière version de Grouper (5.13.0 à l'heure où l'on débute cette documentation) profite d'un certain nombre d'améliorations :

  • Une interface web unifiée : l'ensemble des manipulations (configuration des 'loaders' comprise) se fait depuis une seule et même interface  ; en 2.3 nous devions jongler avec l'ancienne interface, l'interface light et fichiers de configuration ;
  • Une interface Web qui permet de tout configurer en base de données, là où en 2.3 nous devions éditer un certain nombre de fichiers de configurations ;
  • Une synchronisation des groupes vers le ldap (provisioning) s'appuyant sur les possibilités primitives de grouper via le Grouper Daemon ; nous n'avons plus besoin de PSP et de scripts supplémentaires associés ;
  • Une installation simplifiée via des images Docker que l'on met à jour simplement ; toutes les configurations étant en base de données dont le schéma est mise à jour automatiquement via des DDL.

Modes d'installation

Si la documentation officielle recommande très fortement l'usage de docker (et docker-compose) pour installer un Grouper dans un environnement fonctionnel, dans un premier temps nous sommes partis des sources afin de rester dans un environnement similaire à la version 2.3 tout en nous familarisant avec cette nouvelle version de Grouper. Pour ce faire, nous avons fait une ou 2 modifications réalisées sur le fork ESUP - https://github.com/EsupPortail/grouper-esup/tree/grouper-esup-5 

Nous avons ensuite procédé à une migration vers un environnement sous docker, de manière conforme à ce qui est décrit dans la documentation de Grouper vis-à-vis de son installation.

Octobre 2024, la documentation à jour (attention, un certain nombre de procédures données dans le wiki internet 2 sont obsolètes, notamment autour de groupInstaller !) à ce propos se résume aux pages nommées "Installation by maturity level".

Installation depuis les sources

Nous avons laissé cette partie de la documentation car elle reprend la démarche que l'on (université de rouen) a suivi pour aboutir finalement à une installation sous docker.
Pour les exploitants recherchant une documentation rapide expliquant la   mise en place d'un grouper via docker, passez directement au paragraphe Migration vers une installation sous Docker.

Environnement technique

On utilise une debian bookworm avec :

  1. openjdk 17 installé par paquet
  2. apache-maven-3.9.9 installé manuellement
  3. tomcat9 installé manuellement
  4. postgresql 15 installé par paquet
  5. apache et le mod_shib par paquet

Récupération des sources

cd /opt
git clone https://github.com/EsupPortail/grouper-esup.git
cd /opt/grouper-esup
git checkout -b grouper-esup-5 origin/grouper-esup-5

Compilation

cd /opt/grouper-esup/grouper-parent
mvn clean install

Pour que gsh fonctionne il faut également forcer la récupérer des dépendances ainsi :

cd /opt/grouper-esup/grouper
mvn dependency:copy-dependencies

Apache, mod_shib, Postgresql, Tomcat, ...

L'installation de ces différents composants ne change pas vraiment par rapport à la version 2.3,  notons simplements quelques points :

  • Côté Tomcat, on modifiera le server.xml pour définir le contexte /grouper ainsi : 
<Context docBase="/opt/grouper-esup/grouper-misc/webapp/grouper-ui-webapp/target/grouper-ui-webapp-5.0.0-SNAPSHOT.war" path="/grouper" reloadable="false"/>

Récupération des données et configurations de l'installation de Grouper 2.3

Configurations

Vous pouvez récupérer l'essentiel de vos configurations via simples copies des fichiers properties donnés dans le répertoire grouper/conf

Pour la partie PSP (fichiers XML) qui n'est plus nécessaire, voir ci-après. 
Il faudra cependant fournir un fichier subject.properties en conséquence.

Dans le fork esup, nous proposons ces fichiers d'exemple à modifier pour s'adapter à votre ldap notamment :

Base de données

Un dump et restore postgresql de la base grouper doit pouvoire fonctionner.

Voir ci-après pour la mise à jour via DDL.

GSH

On pourra lancer gsh ainsi (le répertoire de lancement est important, la récupération des dépendances, cf ci-dessous, est requise) :

cd /opt/grouper-esup/
./grouper/bin/gsh.sh

Grouper Daemon

Avec un gsh fonctionnel on pourra lancer le grouper dameon via un systemd ainsi configuré - fichier /etc/systemd/system/grouper-loader-daemon.service


# Systemd unit file for grouper-loader-daemon
[Unit]
Description=Synchro incrementale grouperloader (bases de données) vers grouper
After=syslog.target network.target

[Service]
EnvironmentFile=/opt/grouper-env
ExecStart=/opt/grouper-esup/grouper/bin/grouper-loader-daemon

User=grouper
Group=grouper

[Install]
WantedBy=multi-user.target

Mise à jour de la base de données

Dans un premier temps, si le tomcat ne se lance pas, repérez les DDL à lancer.

Dans les logs tomcat, vous trouverez

/opt/tomcat-grouper/logs/catalina.out:2024-10-09 17:08:52 ERROR GrouperDdlUtils:880 - Run this DDL:
/opt/tomcat-grouper/logs/catalina.out-/opt/grouper-esup/grouper/ddlScripts/grouperDdl_20241009_17_08_52_712.sql

Lancez alors les DDL manuellement depuis psql (\i) sous l'utilisateur utilisé par grouper.

Une fois le tomcat et le grouper daemon lancé, la mise à jour de la base de données se fait via l'interface web (pas besoin ainsi de lancer manuellement chaque DDL).

Si tout se passe bien, l'ensemble de vos groupes et configurations sont ainsi restés compatibles avec cette nouvelle version de grouper

Web-Service, packaging, grouperInstaller et génération des images Docker de Grouper ?

Si la partie UI peut être déployée depuis les sources via quelques adaptations (cf les diffs proposés par le fork esup et la commande 'mvn dependency:copy-dependencies' notamment), la partie Web-Service devrait l'être tout autant car elle correspond +/- au même webapp a priori avec des services/librairies différentes.

Cependant le packaging sous maven n'est pas clair, il apparait en effet que tout est pensé pour une exploitation depuis les images Docker.

L'ensemble du packaging se fait sans doute au travers de tâches appelant le GrouperInstaller qui ne doit cependant plus être directement utilisé par les exploitants qui sont encouragés pour leur part à utiliser les images docker officielles proposées sur le hub docker : https://hub.docker.com/r/i2incommon/grouper

La question de la possibilité de reconstruire ces images docker depuis les sources peut se poser, a priori il n'y a pas de documentation à ce sujet ou nous ne l'avons pas trouvée ?

Migration vers une installation sous Docker

Cf l'expérimentaion ci-dessus de la mise en place de Grouper depuis les sources et si on suit la documentation officielle, il est très fortement recommandé de faire fonctionner Grouper sous docker.

La documentation à suivre à ce propos (attention à ne pas consulter de documentations obsolètes) se trouve actuellement (octobre 2024) ici :

Quelques partis pris vis-à-vis de l'exploitation de Grouper sous Docker.

  1. De notre installation précédente, on conserve le apache avec le mod_shib sur le host ainsi que la base de données postgresql.

  2. On fait en sorte d'avoir un minimum de configurations sous forme de fichiers de configurations à plat ; dit autrement, on importe toutes les configurations dans la base de données.
    On fait cela via l'interface graphique. 
    Depuis Home > Miscellaneous > Configure > Configuration files on importe les fichiers de notre répertoire conf
    Seul le fichier morphString.properties restera en fichier à plat pour y indiquer une clef de chiffrement ; en plus de cette configuration, le grouper n'a besoin en configuration docker que des paramètres de connexion à la base de données

  3. On fait donc tourner sous docker les services grouper à proprement parler, avec un container par usage : 1 pour l'interface web, 1 pour le web-service et 1 pour le daemon.

  4. Nous proposons ici l'usage d'un simple docker-compose.yml afin de tout consolider dans un seul fichier (mais on aurait pu se contenter d'appeler directement du docker simplement), un établissement ayant une infrastructure de conteneurisation se passera du docker-compose pour privilgier son orchestrateur en place.

Configurations Docker compose des services Grouper

En suivant les documentations officielles et en l'adaptant à un docker-compose, on a finalement un répertoire de travail /opt/grouperContainer contenant simplement 4 fichiers !

  • docker-compose.yml
  • grouper.env
  • logo_univrouen.png
  • slashRoot/opt/grouper/grouperWebapp/WEB-INF/classes/morphString.properties

docker-compose.yml

On déclare l'ensemble des services grouper dans ce même fichier.

services:

  grouper-ui:
    image: "i2incommon/grouper:5.13.1"
    restart: always
    ports:
      - '8009:8009'
    command:
      - ui
    env_file: "grouper.env"
    environment:
     - GROUPER_TOMCAT_AJP_PORT=8009
    volumes:
      - ./slashRoot:/opt/grouper/slashRoot
      - /var/log/grouper-ui-logs:/opt/grouper/logs
      - ./logo_univrouen.png:/opt/grouper/grouperWebapp/grouperExternal/public/assets/images/logo_univrouen.png
      
  grouper-ws:
    image: "i2incommon/grouper:5.13.1"
    restart: always
    ports:
      - '7009:7009'
    command:
      - ws
    env_file: "grouper.env"
    environment:
     - GROUPER_TOMCAT_AJP_PORT=7009
    volumes:
      - ./slashRoot:/opt/grouper/slashRoot
      - /var/log/grouper-ws-logs:/opt/grouper/logs      

  grouper-daemon:
    image: "i2incommon/grouper:5.13.1"
    restart: always
    command:
      - daemon
    env_file: "grouper.env"
    volumes:
      - ./slashRoot:/opt/grouper/slashRoot      
      - /var/log/grouper-daemon-logs:/opt/grouper/logs

grouper.env

permet de regrouper et mutualiser les configurations à la base de données notamment pour les 3 container grouper

GROUPER_DATABASE_PASSWORD=esup
GROUPER_DATABASE_USERNAME=grouper
GROUPER_DATABASE_URL=jdbc:postgresql://grosville:5432/grouper
GROUPER_AUTO_DDL_UPTOVERSION=v5.*.*
GROUPER_TOMCAT_HTTPS_PORT=-1
GROUPER_WS_GROUPER_AUTH=true
GROUPER_LOG_TO_HOST=true
GROUPER_UI_CONFIGURATION_EDITOR_SOURCEIPADDRESSES=192.168.0.3


slashRoot/opt/grouper/grouperWebapp/WEB-INF/classes/morphString.properties

pour définir une clef de chiffrement simplement

encrypt.key = 123456789azerty

Configurations systemd

L'idée est de proposer ici un service par container pour pouvoir les relancer facilement, on utilise cependant une seule déclaration systemd puisque la définition de chaque service est similaire.

[Unit]
Description=Grouper %i service with docker compose
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=true
WorkingDirectory=/opt/grouperContainer
ExecStart=/usr/bin/docker compose up grouper-%i -d --remove-orphans
ExecStop=/usr/bin/docker compose down grouper-%i

[Install]
WantedBy=multi-user.target

On active donc un service par container : 

systemctl enable grouper-docker-compose@ui
systemctl enable grouper-docker-compose@ws
systemctl enable grouper-docker-compose@daemon

Conclusion

L'installation est ainsi extrêmement simplifiée via Docker.

La mise à jour est théoriquement également très simplifiée : le simple changement du numéro de version de grouper dans le fichier docker-compose.yml et un redémarrage des services suffit.

Les configurations peuvent être exportées/importées depuis l'IHM, ou directement modifiées via le formulaire de configuration.

Exemple de modification de la configuration permettant de changer le logo de l'application : 

Astuce Migration

Si vous êtes passés par l'étape d'installation de grouper depuis les sources, vous avez pu mettre à jour la base deonnées via l'IHM avant de passer en docker ; sinon, vous êtes confrontés au fait qu'il faut configurer dans l'IHM les sources de données pour pouvoir s'authentifier dans l'application... mais que pour s'authentifier, il faut aoir au préalable configuré les sources de données.

Dans ce cas là, et dans un premier temps, modifiez le docker-compose / service grouper-ui pour y apposer des configurations fichiers de subject.properties et grouper-loader.properties via les volumes :

      - ./subject.properties:/opt/grouper/grouperWebapp/WEB-INF/classes/subject.properties
      - ./grouper-loader.properties:/opt/grouper/grouperWebapp/WEB-INF/classes/grouper-loader.properties

Un exemple de ces fichiers est donné sur le github esup : 

Dès que vous aurez accés à l'interface web vous pourrez importer directement les configurations de ces fichiers en base et ne plus avoir besoin de monter ces configurations en tant que volume (pour l'import, votre IP doit référencée dans  la variable d'environnement GROUPER_UI_CONFIGURATION_EDITOR_SOURCEIPADDRESSES - cf le fichier grouper.env donnéé ci-dessus).

Dans la phase de migration, pensez au passage à ne démarrer que grouper-ui pour tout mettre au point, et ne lancez le daemon qu'une fois que tout est bien (re)paramétré en base.

Le premier démarrage va passer toutes les DDL de manière automatique, grâce à la variable d'environnement GROUPER_AUTO_DDL_UPTOVERSION=v5.. ; vous devrez aussi ensuite lancer la mise à jour de la base de données via l'interface web.


Pour les Web Services, afin de pouvoir les utiliser via un simple login/password, on allume un gsh depuis un container docker puis on lance une commande gsh : 


docker ps
docker exec -it dc48872f813a bash
sudo -u tomcat /bin/bash
./bin/gsh.sh
new GrouperPasswordSave().assignApplication(GrouperPassword.Application.WS).assignUsername("monGrouperWsUser").assignPassword("monGrouperWsPassword").save();

Ldap Provisionning

Passage de PSP au Ldap Provisionning

Une partie des configurations Ldap sont données dans les fichiers (à importer en base de données)

Comme dit ci-dessus, la logique des nouvelles versions de Grouper est de privilégier les configurations en base de données (permettant ainsi de tout avoir en base et de faciliter les montées de version en passant d'un container docker à un autre proposant une version plus à jour de grouper).

Aussi l'interface graphique permet de saisir l'ensemble des configurations permettant cette synchro grouper→ldap depuis le menu Home > Miscellaneous > Provisioning.

La configuration est cependant assez ardue, même en utilisant la facilité du "Ldap 'start with'" lorsqu'on ajoute un provisionner.

Si vous avez une configuration qui suit les recommandations supann et ce qu'on présentatit dans la documentation à propos de la version de grouper 2.3 (usage de groupOfNames, groupes à plat, overlay pour le memberOf, ...), le "start with" avec "flatGroupsWithMembershipDNs" aide grandement mais quelques subtilités restent à préciser.

Aussi nous proposons ici une configuration que l'on a exportée et que vous pouvez importer via l'interface web depuis Home > Configure >  Configuration files : grouper-loader.properties

Une fois le group-loader.properties importée, vous retrouvez dans  Home > Miscellaneous > Provisioning le provisionner ldapGroups.

N'hésitez pas alors à lancer l'outil de "Dignostics".

Daemons de synchro → ldap

2 daemons doivent être définis : CHANGE_LOG_consumer_ldapGroupgSyncInc et OTHER_JOB_ldapGroupgSyncFull - si ce n'est pas le cas ajoutez les 

  • le premier, de type edu.internet2.middleware.grouper.app.provisioning.ProvisioningConsumer, permet de faire la synchro régulière toutes les minutes (en production, nous avons finalement opté pour toutes les 10sec.) ;
  • le deuxième, de type edu.internet2.middleware.grouper.app.provisioning.GrouperProvisioningFullSyncJob, permet de consolider au besoin l'ensemble.

Configuration des dossiers à provisionner

Pour chaque dossier 'racine', vous pouvez indiquer que l'ensemble de leurs groupes enfant doivent être reversés dans votre LDAP.
Attention, suivant la configuration de votre provisioning, ne pas indiquer de groupes à 'provisioner' peut revenir à dire à grouper de supprimer tous les groupes du ldap (cf la propriété provisioner.ldapGroups.deleteGroupsIfNotExistInGrouper=true donnée dans le fichier grouper-loader.properties ).

Copies d'écran d'interfaces indiquant que les daemons jobs ldap sont fonctionnels

Purges

La purge des utilisateurs qui ne sont plus présents dans le ldap et qui doivent être supprimés de Grouper ne se fait plus par gsh mais par un daemon de manière automatique

→ à vérifier

Debug

Si vous avez besoin de faire du debug pour détecter un comportement suspect ou un problème, le grouperdaemon peut se lancer en mode debug comme toute application Java, à vous ensuite d'utiliser un IDE (eclipse ou idea) permettant de positionner des breakpoints et autres.

Exemple d'arguments java à ajouter au daemon :

-Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=4000,suspend=n 

Sous docker, la mise en place de cela demandera un peu plus de modifications : surcharge de configurations voire de fichiers et exposition du port (4000 ici).

Consommation CPU

Par rapport à une installation 2.3, qui utilisait notamment PSP pour mettre à jour les groupes vers ldap, la consommation CPU est moindre, alors même que les synchronisations de groupes sont plus réactives.

Sur le graphe ci-dessous, la migration de Grouper 2.3 vers 5 (sous docker) a été opérée le 23 octobre.

La migration de Grouper 2.3 vers 5 (sous docker) a été opérée le 23 octobre, le graphe montre que la consommation cpu est moindre à partir de cette date (divisée par 3 voir 4).


  • Aucune étiquette