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._
* *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 		«&nbsp;*{*}emptySessionPath=true&nbsp;» à 		toutes les balises <connector>&nbsp;:\*
| {color:#000000}<Connector 					emptySessionPath="true" acceptCount="100" 					connectionTimeout="20000"{color} |

* *Lancement de Tomcat*
* \*Modification des 	fichiers de configuration&nbsp;:\* * {color:#000000}Modification 	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}&nbsp;\* \*Construction du 	projet par compilation maven via le script ant&nbsp;:\*

** {color:#000000}Initialisation 	et compilation de l'application : se 	placer dans le répertoire /ESCO-Grouper et lancer la commande&nbsp;:{color}ant 				init
+Attention&nbsp;:+ 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&nbsp;:{color}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.\*

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&nbsp;: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}*/\!\{*{color}{color:#ff0000}} Tomcat prend en compte le nouveau war&nbsp;de la façon suivante&nbsp;:
* 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&nbsp;: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.

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&nbsp;: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.

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&nbsp;: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.

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 «&nbsp;undeploy&nbsp;» 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&nbsp;: 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 «&nbsp;kerberos principal used to connect to ldap&nbsp;». 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 «&nbsp;password for shared secret authentication to ldap or you can put a filename with an encrypted password&nbsp;». 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 | p { margin-bottom: 0.21cm; }Niveau de log dans l'ensemble de l'application. Les valeurs possibles sont DEBUG, INFO, WARN, ERROR, FATAL | DEBUG\\ |
| p { margin-bottom: 0.21cm; }log4j.appender.grouper_event.File | p { margin-bottom: 0.21cm; }Fichier de log des événements Grouper | |
| p { margin-bottom: 0.21cm; }log4j.appender.grouper_error.File | p { margin-bottom: 0.21cm; }Fichier de log des erreurs Grouper | |
| p { margin-bottom: 0.21cm; }log4j.appender.grouper_debug.File | p { margin-bottom: 0.21cm; }Fichier de log du debug Grouper | |
| p { margin-bottom: 0.21cm; }log4j.appender.grouper_gb.File | p { margin-bottom: 0.21cm; }Fichier de log de Grouper | |
| p { margin-bottom: 0.21cm; }{color:#e51519}{*}SMTP{*}{color} | | |
| p { margin-bottom: 0.21cm; }smtp.host | p { margin-bottom: 0.21cm; }Hôte du serveur SMTP | localhost\\ |
| p { margin-bottom: 0.21cm; }smtp.port | Port du serveur SMTP\\ | 25\\ |
| p { margin-bottom: 0.21cm; }smtp.username | p { margin-bottom: 0.21cm; }Login d'accès au serveur SMTP | |
| p { margin-bottom: 0.21cm; }smtp.password | p { margin-bottom: 0.21cm; }Mot de passe d'accès au serveur SMTP | |
| p { margin-bottom: 0.21cm; }smtp.adress | p { margin-bottom: 0.21cm; }Adresse mail du destinataire | p { margin-bottom: 0.21cm; }ent@esco-portail.org |
| p { margin-bottom: 0.21cm; }smtp.name | p { margin-bottom: 0.21cm; }Nom du destinataire | Administrateurs ENT\\ |
| p { margin-bottom: 0.21cm; }smtp.adressFrom | p { margin-bottom: 0.21cm; }Adresse émettrice des mails | p { margin-bottom: 0.21cm; }devel@esco-portail.org |
| p { margin-bottom: 0.21cm; }smtp.nameFrom | p { margin-bottom: 0.21cm; }Nom émetteur des mails | ESCO-Portail\\ |
| p { margin-bottom: 0.21cm; }smtp.copyAdress | p { margin-bottom: 0.21cm; }p { margin-bottom: 0.21cm; }\\
Adresse de copie des mails | julien.gribonvald@recia.fr\\ |
| error.level | p { margin-bottom: 0.21cm; }Niveau d'erreur pour envoyer les mails | ERROR\\ |
| p { margin-bottom: 0.21cm; }{color:#e51519}{*}GROUPES DYNAMIQUES{*}{color} | | |
| p { margin-bottom: 0.21cm; }dynamic.group | p { margin-bottom: 0.21cm; }Inclure le plugin des groupes dynamiques au projet (true/false) | true\\ |
| p { margin-bottom: 0.21cm; }dynamic.database.attribute.field.ldaprequest | p { margin-bottom: 0.21cm; }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 { margin-bottom: 0.21cm; }dynamic.group.type | p { margin-bottom: 0.21cm; }Valeur définie dans la table grouper_types et la colonne name. Elle définie le type dynamique. | dynamic\\ |  <!-- p { margin-bottom: 0.21cm; } -->| Niveau de log dans l'ensemble de l'application. Les valeurs 			possibles sont DEBUG, INFO, WARN, ERROR, FATAL |