{toc}
h1. 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 {color:#ff0000}{*}5.5.27{*}{color}
* 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 :
|| {color:#3366ff}CHEMIN{color} || {color:#3366ff}{*}CORRECT OU INCORRECT{*}{color} ||
| C:/Program Files/Tomcat | Incorrect |
| C:/Tomcat | Correct |
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|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).
h1. Restriction
Il n'est pas possible d'avoir deux portlets ESCOGrouper dans le même portail à cause de la session.
h1. Installation de l'application
h2. 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.
h2. Principe général d'installation
_{+}Pré-requis :+_ _Le serveur Tomcat version_ {color:#ff0000}{*}{_}5.5.27{_}{*}{color} _où sera déployée l'application doit être lancé au moment de l'exécution des tâches Ant._
* *Étape 1 :* récupération des sources
* *Étape 2* : modification des options de lancement de Tomcat pour spécifier l'emplacement des fichiers de la mémoire allouée, etc...
|| {color:#888888}\-Xms256m \-Xmx512m \-XX:PermSize=64M \-XX:MaxPermSize=128M \-Xss2048k \-Xminf0.05 \-Xminf0.40 \-Xmaxf0.60{color}\\
{color:#888888}\-Djavax.net.ssl.trustStore=***emplacement du fichier{color} {color:#888888}*.cacerts si mode SSL{*}{color}{color:#888888}\*\*{color} ||
+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.
* *Étape 3 :* si l'installation est en mode portlet, édition du fichier server.xml du serveur Tomcat pour ajout du « *emptySessionPath=true* » à toutes les balises <connector> :
|| {color:#888888}<Connector emptySessionPath="true" acceptCount="100" connectionTimeout="20000"{color} ||
* *Étape 4* : Lancement de Tomcat
* *Étape 5* : Modification des fichiers de configuration :
** m{color:#000000}odification du fichier ESCOGrouper/build.properties (cf. §6.1){color}
** {color:#000000}Modification du fichier ESCOGrouper/properties/ESCOGrouper.properties (cf. §6.2){color}
** {color:#000000}Modification du paramétrage applicatif (base de données DERBY) (cf. §6.3){color}
** {color:#000000}Modification des fichiers d'internationalisation (libellé, aide contextuelle, exception) (cf. §6.4){color}
** {color:#000000}Vérification des stratégies (cf. §6.5){color}
** {color:#000000}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.{color}
** {color:#000000}Vérification du paramétrage du serveur d'envoi de mail (cf. §6.7){color} \* \*Construction du projet par compilation maven via le script ant :\*
* *Étape 6* : Construction du projet par compilation maven via le script ant :
** {color:#000000}Initialisation et compilation de l'application : se placer dans le répertoire /ESCO-Grouper et lancer la commande :{color}
|| {color:#888888}ant init{color}\\ ||
+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.
** {color:#000000}Déploiement : se placer dans le répertoire /ESCO-Grouper et lancer la commande :{color}
|| {color:#888888}ant deploy{color}\\ ||
* *Étape 7* : Modification des fichiers d'aide en ligne si nécessaires (cf. §6.8).
* *Étape 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.
h2. 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 :
|| {color:#888888}ant init{color}\\
{color:#888888}ant deploy{color}\\ ||
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.
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
h2. 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 :
|| {color:#888888}ant init{color}\\
{color:#888888}ant deploy{color}\\ ||
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.
h2. 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 :
|| {color:#888888}ant dbinit{color}\\
{color:#888888}ant dbdeploy{color}\\ ||
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.
h2. 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 :
|| {color:#888888}ant init{color}\\
{color:#888888}ant dbdeploy{color}\\
{color:#888888}ant deploy{color} ||
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.
h1. Les tâches ant
h2. 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.
h2. 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.
h2. 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.
h2. 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.
h2. 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é.
h2. 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.
h1. Configurations techniques et applicatives
L'ensemble des fichiers de configuration à modifier se trouvent dans le répertoire /ESCO-Grouper/properties.
h2. build.properties
Il s'agit du fichier d'environnement nécessaire à la compilation via la tâche ant.
|| {color:#3366ff}Clef{color} || {color:#3366ff}{*}Description{*}{color} || {color:#3366ff}{*}Exemple{*}{color} ||
| 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 |
| {color:#e51519}{*}MAVEN{*}{color} | | |
| 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 |
| {color:#e51519}{*}TOMCAT{*}{color} | | |
| 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 |
h2. ESCOGrouper.properties
Il s'agit du fichier de propriétés de l'application ESCO-Grouper.
|| Clef \\ || Description \\ || Exemple \\ ||
| {color:#e51519}{*}APPLICATION{*}{color} | | |
| 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 \\ |
| {color:#e51519}{*}CAS{*}{color} | | |
| 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 |
| {color:#e51519}{*}LDAP{*}{color} | | |
| 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 |
| {color:#e51519}{*}BASE DE DONNÉES GROUPER{*}{color} | | |
| 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 |
| {color:#e51519}{*}BASE DE DONNÉES MÉMOIRE DERBY{*}{color} | | |
| 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 \\ |
| {color:#e51519}{*}GROUPER WS{*}{color} | | |
| 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 \\ |
| {color:#e51519}{*}LOG4J{*}{color} | | |
| log4j.level | Niveau de log dans l'ensemble de l'application. Les valeurs possibles sont DEBUG, INFO, WARN, ERROR, FATAL | DEBUG \\ |
| log4j.appender.grouper_event.File | Fichier de log des événements Grouper | |
| log4j.appender.grouper_error.File | Fichier de log des erreurs Grouper | |
| log4j.appender.grouper_debug.File | Fichier de log du debug Grouper | |
| log4j.appender.grouper_gb.File | Fichier de log de Grouper | |
| {color:#e51519}{*}SMTP{*}{color} | | |
| smtp.host | Hôte du serveur SMTP | localhost \\ |
| smtp.port | Port du serveur SMTP \\ | 25 \\ |
| smtp.username | Login d'accès au serveur SMTP | |
| smtp.password | Mot de passe d'accès au serveur SMTP | |
| smtp.adress | Adresse mail du destinataire | ent@esco-portail.org |
| smtp.name | Nom du destinataire | Administrateurs ENT \\ |
| smtp.adressFrom | Adresse émettrice des mails | devel@esco-portail.org |
| smtp.nameFrom | Nom émetteur des mails | ESCO-Portail \\ |
| smtp.copyAdress | Adresse de copie des mails | julien.gribonvald@recia.fr \\ |
| error.level | Niveau d'erreur pour envoyer les mails | ERROR \\ |
| {color:#e51519}{*}GROUPES DYNAMIQUES{*}{color} | | |
| dynamic.group | Inclure le plugin des groupes dynamiques au projet (true/false) | true \\ |
| dynamic.database.attribute.field.ldaprequest | 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 \\ |
| dynamic.group.type | Valeur définie dans la table grouper_types et la colonne name. Elle définie le type dynamique. | dynamic |
h2. Paramétrage applicatif (base de données DERBY)
Le paramétrage est un élément important de l'application, tous les écrans y font appel pour décider si tels éléments doivent être affichés ou non.
Cette brique technique se doit d'être le plus ouvert et le plus simple possible. Ainsi l'utilisation d'une base de données mémoire est recommandée dans ce type de configuration car elle est :
* Souple d'utilisation grâce à un accès distant ;
* Accessible par de multiples modules ;
* Modifiable à chaud.
Or des fichiers de configurations permettent d'alimenter simplement cette base de données et de créer les fichiers d'internationalisation correspondant.
Chaque fichier contient la manière de paramétrer les différentes pages => se référer aux fichiers fournis dans les sources.
Les fichiers sont référencés dans le fichier build.xml. En modifiant build.xml, on peut modifier le nom et le nombre des fichiers de paramétrage applicatif.
h3. MyParameters.properties
Ce fichier permet de renseigner des paramètres
* nécessaires à la génération de la base de données,
* communs à l'ensemble de l'application et qui sont nécessaires au bon fonctionnement de l'application.
_global.lang_ permet de définir les langues utilisées par l'application et ainsi vérifier lors de la génération des fichiers d'internationalisation que les libellés sont paramétrés dans l'ensemble des langues définies.
_default.rule.regexp.\*_ définit l'expression régulière utilisée si aucune autre expression n'est définie pour la validation des champs.
h3. MySearch.properties
Ce fichier concerne le paramétrage des pages relatives aux recherches :
* Recherche de sujets :
* {color:#000000}Personnes{color}
* {color:#000000}Groupes{color}
* {color:#000000}Personnes dans un groupe{color}
* Recherche de dossiers<!-- h3 { text-indent: -1.21cm; margin-top: 0.64cm; margin-bottom: 0.21cm; color: rgb(0, 0, 0); widows: 2; orphans: 2; }h3.western { font-family: "Century Gothic",sans-serif; font-size: 12pt; font-weight: normal; }h3.cjk { font-family: "Arial",sans-serif; font-size: 12pt; font-weight: normal; }h3.ctl { font-family: "Times New Roman",serif; font-size: 12pt; font-weight: normal; }p { margin-bottom: 0.21cm; } -->
h3. MySearch.properties
Ce fichier concerne le paramétrage des pages relatives aux recherches :
* Recherche de sujets :
* {color:#000000}Personnes{color}
* {color:#000000}Groupes{color}
* {color:#000000}Personnes dans un groupe{color}
* Recherche de dossiers |