Pré-requis

Afin d'effectuer l'installation de l'application ESCO-Grouper, certains logiciels/outils sont nécessaires :

• Maven 2.2.1
• Apache ant 1.8.0
• Tomcat 5.5.27
• Un éditeur de texte (ex : Bloc Note)

L'installation de Maven, Tomcat et du projet doit se faire dans des répertoires dont le chemin ne contient pas le caractère espace. Par exemple :

Grouper 1.6.2 et son web service doivent être installés et accessibles, y compris la base de données Grouper pour les accès via l'API.

Le web service de Grouper doit contenir le fichier esco-subject-extension-1.1.jar dans le répertoire lib afin de récupérer des attributs multi-valués du LDAP sur une personne (correction du bug Grouper https://bugs.internet2.edu/jira/browse/GRP-257).

Le fichier sources.xml de grouper-ws doit contenir les attributs LDAP à afficher dans l'application (voir un exemple plus bas).

Restriction

Il n'est pas possible d'avoir deux portlets ESCOGrouper dans le même portail à cause de la session.

Installation de l'application

Paramétrage et configuration

Aucune modification de configuration ou de paramétrage dans la base de données DERBY n'est à faire entre le v2.5.00 et la v2.6.00 de l'application.

Principe général d'installation

Pré-requis : Le serveur Tomcat version 5.5.27 où sera déployée l'application doit être lancé au moment de l'exécution des tâches Ant.

• Récupération des sources

• *Modification des options de lancement de Tomcat pour spécifier l'emplacement des fichiers de la mémoire allouée, etc... :* -Xms256m -Xmx512m -XX:PermSize=64M -XX:MaxPermSize=128M -Xss2048k -Xminf0.05 -Xminf0.40 -Xmaxf0.60
  -Djavax.net.ssl.trustStore=***emplacement du fichier .cacerts si mode SSL**
  Remarque : les options de lancement concernant la langue, l'encodage et le répertoire --Dconf.dir ne sont plus nécessaires depuis la version 2.4.00.
• *Si l'installation est en mode portlet,* *Edition du fichier server.xml du serveur Tomcat pour ajout du « {}emptySessionPath=true » à toutes les balises <connector> :*

  <Connector emptySessionPath="true" acceptCount="100" connectionTimeout="20000"

• Lancement de Tomcat
• *Modification des fichiers de configuration :* * Modification du fichier ESCOGrouper/build.properties (cf. §6.1)
• Modification du fichier ESCOGrouper/properties/ESCOGrouper.properties (cf. §6.2)
• Modification du paramétrage applicatif (base de données DERBY) (cf. §6.3)
• Modification des fichiers d'internationalisation (libellé, aide contextuelle, exception) (cf. §6.4)
• Vérification des stratégies (cf. §6.5)
• Vérification des profils (cf. §6.6). Ces profils peuvent être modifiés directement sur le serveur Tomcat après déploiement. Par contre cela nécessite un redémarrage du serveur pour prendre en compte les modifications.
• Vérification du paramétrage du serveur d'envoi de mail (cf. §6.7) * *Construction du projet par compilation maven via le script ant :*

• • Initialisation et compilation de l'application : se placer dans le répertoire /ESCO-Grouper et lancer la commande :ant init
    Attention : le fait d'avoir BUILD SUCCESSFUL en fin de script ANT ne signifie pas forcément que la compilation s'est bien déroulée. Il faut vérifier qu'il n'y ait pas de BUILD FAILED dans les tâches maven au dessus.
  • Déploiement : se placer dans le répertoire /ESCO-Grouper et lancer la commande :ant deploy
• *Modification des fichiers d'aide en ligne si nécessaires (cf. §6.8).*

• *Pour le mode portlet, il est nécessaire de copier les css dans les thèmes du portail. Le fichier à copier se trouve dans le répertoire ESCOGrouper/properties/css.*

Cas de la première installation

Dans le cas où l'application n'a jamais été installée et la base de données mémoire n'existe pas.

Se placer dans le répertoire /ESCO-Grouper et lancer les commandes :ant init
ant deploy
Quand Tomcat prend en compte le nouveau war, la base de données mémoire est créée avec le paramétrage fourni à l'étape 5.

/!{{color:#ff0000}} Tomcat prend en compte le nouveau war de la façon suivante :

• En mode remote, prise en compte à chaud
• En mode local, redémarrage de Tomcat

Cas d'une installation avec modification des propriétés autres que derby

Dans le cas où l'application est déjà installée et la base de données mémoire existe déjà. Si l'on souhaite modifier les fichiers du répertoire /properties autres que ceux de derby (les stratégies par exemple).

Se placer dans le répertoire /ESCO-Grouper et lancer les commandes :ant init
ant deploy
Quand Tomcat prend en compte le nouveau war, la base de données mémoire n'est pas modifiée par rapport à l'installation précédente.

Cas d'une installation avec modification des propriétés derby

Dans le cas où l'application est déjà installée et la base de données mémoire existe déjà. Si l'on souhaite seulement modifier le paramétrage applicatif (fichiers de propriétés derby).

Se placer dans le répertoire /ESCO-Grouper et lancer les commandes :ant dbinit
ant dbdeploy
La seconde tâche copie les fichiers générés (sql + label), supprime la base de données derby existante et alimente la base avec le nouveau paramétrage.

Ceci est vrai dans le cas du déploiement en mode local. En mode remote, il faut se référer au cas suivant.

Afin que les fichiers d'internationalisation soient pris en compte, il faut redémarrer Tomcat.

Cas d'une installation avec modification des properties (derby + autre)

Dans le cas où l'application est déjà installée et la base de données mémoire existe déjà. Si l'on souhaite modifier à la fois le paramétrage applicatif (fichiers de propriétés derby) et les autres paramétrages (stratégie par exemple).

Se placer dans le répertoire /ESCO-Grouper et lancer les commandes :ant init
ant dbdeploy
ant deploy
La seconde tâche copie les fichiers générés (sql + label), supprime la base de données derby existante et alimente la base avec le nouveau paramétrage.

Afin que les fichiers d'internationalisation soient pris en compte, il faut redémarrer Tomcat.

Les tâches ant

ant clean

Cette tâche permet de lancer le nettoyage des différents projets afin de pouvoir revenir à un état vierge avant toute nouvelle compilation.

ant init

Cette tâche permet de lancer un dbinit, de copier dans le projet les fichiers générés et de compiler le projet.

ant dbinit

Cette tâche permet de générer le fichier sql permettant d'alimenter la base de données mémoire à partir des fichiers de paramétrage ainsi que les fichiers d'internationalisation.

Cette tâche peut afficher des warning lors de son exécution. Ces warnings correspondent à des clés dupliquées. Dans la majorité des cas, cela est normal car une même clé est utilisée pour le même attribut sur des pages différentes. Par exemple, l'attribut extension est utilisé dans la page de propriétés d'un groupe et dans celle d'un dossier. Le même libellé (extension.label) est utilisé. D'où le warning de la duplication de clé mais qui est normal. Il faut être vigilant sur ces duplications lors que l'on veut des libellés différents pour un même attribut.

ant deploy

Cette tâche permet de déployer le war sur Tomcat.

• En mode remote, cela « undeploy » l'application existe (si elle porte le même nom de contexte) et déploie le nouveau war. Ce war est pris directement en compte par Tomcat.
• En mode local, cela copie l'application dans le répertoire paramétré. Il faut redémarrer Tomcat pour le nouveau war soit pris en compte.

ant dbdeploy

Cette tâche permet de copie les fichiers générés puis supprimer et créer à nouveau la base de données à partir des fichiers généré par la tâche dbinit ou init. Tomcat doit être démaré.

ant undeploy

Cette tâche supprime le war et le répertoire de déploiement sous tomcat que ce soit en mode remote ou en mode local.

Configurations techniques et applicatives

L'ensemble des fichiers de configuration à modifier se trouvent dans le répertoire /ESCO-Grouper/properties.

build.properties

Il s'agit du fichier d'environnement nécessaire à la compilation via la tâche ant.

Clef	Description	Exemple
escogrouper.property.file	Nom du fichier de propriété à utiliser pour la compilation situé dans le répertoire /ESCO-Grouper/properties	ESCOGrouper.properties
javascript.compression	Compiler en utilisant le mode de compression des JavaScript	true
MAVEN
maven.home	Répertoire où se situe Maven	/opt/apache-maven-2.2.0
maven.offline	Compilation Maven en mode offline	false
maven.quiet	Niveau de commentaire des tâches Maven. Affiche seulement les erreurs si en mode true.	false
TOMCAT
tomcat.deploy.mode	Détermine le mode de déploiement en local (local) ou à distance (remote). A distance, le déploiement utilise le manager Tomcat. En local, le déploiement s'effectue par copie.	local
tomcat.webapps.directory	Répertoire de déploiement dans le cas du mode local	/opt/tomcat/webapps
tomcat.host	Url d'accès au manager du Tomcat. Cette url est nécessaire pour le déploiement de l'application en mode remote.	http://escogrouper:8090/manager
tomcat.user	Login du compte à utiliser pour se connecter au manager (mode remote)	manager
tomcat.password	Mot de passe du compte à utiliser pour se connecter au manager (mode remote)	manager

ESCOGrouper.properties

Il s'agit du fichier de propriétés de l'application ESCO-Grouper.

Clef	Description	Exemple
APPLICATION
application.version	Version de l'application (donné à titre indicatif)	2.6.0
application.versionMajorNumber	Version de l'application (donné à titre indicatif)	2
application.versionMinorNumber	Version mineure de l'application. Utilisé par application.xml pour afficher le numéro de version en bas de page.	6
application.versionUpdate	Version update de l'application. Utilisé par application.xml pour afficher le numéro de version en bas de page.	0
application.env	Environnement de l'application (donné à titre indicatif). Les valeurs possibles sont Test, Production, Développement, ...	test
application.type	Type de compilation. Les valeurs possibles sont servlet ou portlet.	servlet
application.portlet.name	Nom de la portlet. Ignorer en mode servlet.	ESCOGrouperPortlet
application.host	Hôte de l'application : adresse IP ou adresse DNS du serveur Tomcat	escogrouper.esco-portail.org
application.context	Contexte de l'application	ESCOGrouper
application.port	Port d'accès à l'application	443
CAS
cas.mode	Mode d'utilisation de CAS (http, https)	https
cas.host	Hôte de CAS	auth.esco-portail.org
cas.port	Port d'accès à CAS	443
cas.uri	URI de CAS. Le / est nécessaire en début de chaîne.	/
cas.uri.login	URI du login de CAS. Le / est nécessaire en début de chaîne.	/login
cas.uri.logout	URI du logout de CAS. Le / est nécessaire en début de chaîne.	/logout
cas.uri.validate	URI du validate de CAS. Le / est nécessaire en début de chaîne.	/proxyValidate
cas.uri.proxyCallback	URI du callback de CAS. Le / est nécessaire en début de chaîne.	/casProxyCallback
LDAP
ldap.host	Hôte du serveur LDAP	172.31.142.71
ldap.port	Port du serveur LDAP	389
ldap.login	Login du serveur LDAP Utilisé dans le fichier grouper.client.properties, ce login représente « kerberos principal used to connect to ldap ». Cette clé n'est utilisée que dans le cas de kerberos. Dans les autres cas elle est mise en commentaire.	admin
ldap.password	Mot de passe du serveur LDAP Utilisé dans le fichier grouper.client.properties, ce login représente « password for shared secret authentication to ldap or you can put a filename with an encrypted password ». Cette clé n'est utilisée que dans le cas de kerberos. Dans les autres cas elle est mise en commentaire.	passwd
ldap.dn	Le compte admin du LDAP	cn=grouper,dc=esco-portail,dc=org
ldap.dn.password	Mot de passe du compte admin du LDAP	passwd
ldap.basedc	Dc du serveur LDAP	dc=esco-portail,dc=org
ldap.baseuid	Branche qui contient les comptes utilisateur du serveur LDAP	ou=people,dc=esco-portail,dc=org
BASE DE DONNÉES GROUPER
database.driver	Driver de la base de données	com.mysql.jdbc.Driver
database.username	Login de connexion à la base de données Grouper	esco
database.password	Mot de passe pour se connecter à la base de données Grouper	passwd
database.url	Url de la base de données Grouper	jdbc:mysql://172.31.142.71:3306/ grouper?characterEncoding=UTF-8
BASE DE DONNÉES MÉMOIRE DERBY
derby.driver	Driver de la base de données	org.apache.derby.jdbc.ClientDriver
derby.port	Port d'écoute de la base de données	1527
derby.url	Url d'accès à la base de données. Sous linux, les des slashs (//opt) sont obligatoires.	jdbc:derby://localhost:1527//opt/conf.dir/data/ESCODB;create=true;
derby.username	Utilisateur de la base de données	sa
derby.password	Mot de passe de l'utilisateur de la base	passwd
derby.requireAuthentication	Authentification requise ou non pour accéder à la base de données (true, false)	true
GROUPER WS
grouperClient.webService.url	Url d'appel des web-services Grouper	http://172.31.142.71:8080/grouper-ws/servicesRest/
grouperClient.webService.login	Login de connexion aux web-services	Apd00000
grouperClient.webService.password	Mot de passe de connexion aux web-service	passwd
LOG4J
log4j.level	p Unknown macro: { margin-bottom} Niveau de log dans l'ensemble de l'application. Les valeurs possibles sont DEBUG, INFO, WARN, ERROR, FATAL	DEBUG
p Unknown macro: { margin-bottom} log4j.appender.grouper_event.File	p Unknown macro: { margin-bottom} Fichier de log des événements Grouper
p Unknown macro: { margin-bottom} log4j.appender.grouper_error.File	p Unknown macro: { margin-bottom} Fichier de log des erreurs Grouper
p Unknown macro: { margin-bottom} log4j.appender.grouper_debug.File	p Unknown macro: { margin-bottom} Fichier de log du debug Grouper
p Unknown macro: { margin-bottom} log4j.appender.grouper_gb.File	p Unknown macro: { margin-bottom} Fichier de log de Grouper
p Unknown macro: { margin-bottom} SMTP
p Unknown macro: { margin-bottom} smtp.host	p Unknown macro: { margin-bottom} Hôte du serveur SMTP	localhost
p Unknown macro: { margin-bottom} smtp.port	Port du serveur SMTP	25
p Unknown macro: { margin-bottom} smtp.username	p Unknown macro: { margin-bottom} Login d'accès au serveur SMTP
p Unknown macro: { margin-bottom} smtp.password	p Unknown macro: { margin-bottom} Mot de passe d'accès au serveur SMTP
p Unknown macro: { margin-bottom} smtp.adress	p Unknown macro: { margin-bottom} Adresse mail du destinataire	p Unknown macro: { margin-bottom} ent@esco-portail.org
p Unknown macro: { margin-bottom} smtp.name	p Unknown macro: { margin-bottom} Nom du destinataire	Administrateurs ENT
p Unknown macro: { margin-bottom} smtp.adressFrom	p Unknown macro: { margin-bottom} Adresse émettrice des mails	p Unknown macro: { margin-bottom} devel@esco-portail.org
p Unknown macro: { margin-bottom} smtp.nameFrom	p Unknown macro: { margin-bottom} Nom émetteur des mails	ESCO-Portail
p Unknown macro: { margin-bottom} smtp.copyAdress	p Unknown macro: { margin-bottom} p Unknown macro: { margin-bottom} Adresse de copie des mails	julien.gribonvald@recia.fr
error.level	p Unknown macro: { margin-bottom} Niveau d'erreur pour envoyer les mails	ERROR
p Unknown macro: { margin-bottom} GROUPES DYNAMIQUES
p Unknown macro: { margin-bottom} dynamic.group	p Unknown macro: { margin-bottom} Inclure le plugin des groupes dynamiques au projet (true/false)	true
p Unknown macro: { margin-bottom} dynamic.database.attribute.field.ldaprequest	p Unknown macro: { margin-bottom} Valeur définie dans la table grouper_fields et la colonne name. Cette valeur est l'attribut où sera sauvegardée la requête LDAP.	rule
p Unknown macro: { margin-bottom} dynamic.group.type	p Unknown macro: { margin-bottom} Valeur définie dans la table grouper_types et la colonne name. Elle définie le type dynamique.	dynamic	<!-- p Unknown macro: { margin-bottom} -->	Niveau de log dans l'ensemble de l'application. Les valeurs possibles sont DEBUG, INFO, WARN, ERROR, FATAL