Installation du package esup-portail
Ce document décrit l'installation et la première prise en main
du package du socle esup-portail' issu de la version 2.4 d'uPortal.
Ce package contient l'installation d'un serveur Tomcat, de la distribution
uPortal 2.4 (branche rel-2.4) et des librairies et personnalisations propres
à l'environnement esup-portail (voir le document sur les groupes
esup-portail proposés).
Il permet de simplifier considérablement le paramétrage de base
d'uPortal.
Le package ne livre pas les différents canaux esup-portail, à
installer indépendamment .
Téléchargement.
Changelog.
Le sommaire de ce document est le suivant :
Conseils préalables
L'utilisation de l'installation d'Esup-portail issue de ce package nécessite
une bonne connaissance préalable d'uPortal, de l'environnement Esup-portail
et de l'authentification CAS.
Si ce n'est pas le cas, la bonne stratégie de prise en main est d'utiliser
le package de test et
développement d'esup-portail (sous windows ou linux), en suivant
les étapes suivantes :
- Dans un premier temps, utiliser sans l'authentification CAS (esup.cas.auth=false
et esup.cas.proxy=false), et avec l'environnement uPortal (esup.env.esup-portail=false).
On est alors dans un environnement proche de la distribution quick-install
d'uPortal, avec les apports esup (paramétrages LDAP, ...).
Ceci permet d'appréhender le fonctionnement du portail, dans un environnement
permissif (droits élevés aux comptes créés), et
avec des canaux de tests. En particulier, il est important de comprendre le
fonctionnement du gestionnaire de groupes uPortal.
- Ensuite, y ajouter l'authentification CAS (esup.cas.auth=true et esup.cas.proxy=true)
; s'assurer que le portail fonctionne correctement en mode proxy.
- Enfin, paramétrer l'environnement esup-portail (esup.env.esup-portail=true,
et ant esup.db.init); on se retrouve alors dans un environnement très
proche de celui proposé par ce package.
Lorsque vous serez familiarisé avec ce dernier environnement, vous pourrez
appréhender le package esup-portail sans problème.
Pré-requis
L'installation de ce package suppose les pré-requis suivants :
Système d'exploitation
Linux, UNIX.
En pratique, esup-portail a été testé sur Redhat 7.x,
9.0, ES et solaris xxxx
SGBD
Doit fonctionner avec un SGBD acceptant du SQL standard et les transactions,
et proposant un drivers JDBC natif.
Testé avec mysql (version 4 ou supérieure), postgree, oracle.
A noter, pour mysql : ce sgbd ne supporte des transactions qu'avec des
tables de type BDB ou INNODB ; il est donc impératif d'utiliser ce type
de tables pour la base esup-portail.
Environnement java
La JVM (en fait, un SDK, car le portail doit être compilé) doit
être préalablement installée.
La télécharger par exemple à :
http://java.sun.com/j2se/1.4.2/download.html
La variable JAVA_HOME doit être valué, et le chemin $JAVA_HOME/bin
rajouté au PATH
Ant
Le logiciel ant doit être installé.
Le télécharger à :
http://ant.apache.org/
La variable ANT_HOME doit être valuée, et le chemin $ANT_HOME/bin
rajouté au PATH
Authentification
Un serveur CAS est opérationnel au sein de l'établissement, et
testé préalablement.
LDAP
L'établissement doit disposer d'un annuaire LDAP exhaustif et compatible
supann.
Contenu du package
Ce package permet une installation uPortal en y ajoutant des libraries et un
environnement spécifiques esup-portail.
Il apporte également les librairies et le paramétrage permettant
l'utilisation du mécanisme de SSO CAS.
Il installe et paramètre également le serveur Tomcat ; cette
installation reste optionnelle (mais conseillée), afin de permettre à
des établissements désirant utiliser un autre moteur de servlet
de le faire.
Organisation du package
Ce paragraphe décrit l'organisation File Système liée
au package. Il précise l'organisation juste après le décompactage
du package, puis celle qui résulte de la directive 'ant esup.unzip',
qui installe réellement le package.
Organisation File système suite au décompactage du package
Le décompactage du package crée le répertoire uPortal-2.4-esup-1-version
qui est la racine de l'installation (esup.root).
Sous cette racine ,on trouve les fichiers et répertoires suivants :
- esup-2.4.properties : c'est le fichier principal du paramétre
de l'installation. Il est à adapter pour l'installation d'esup-portail.
- default.esup-2.4.properties : c'est un fichier de propriétés
qui paramètre de fonctionnement de l'installation. A ne pas modifier.
- build.xml : c'est le fichier qui contient la logique des différentes
directives liées à l'installation et au paramétrage du
package ; il utilise le fichier précédent pour cela.
Aucune modification ne doit être effectuée sur ce fichier
- env.sh : c'est un fichier script shell appelé par les autres
scripts. Il est mis à jour automatiquement lors de la procédure
d'installation en fonction des informations du fichier esup-2.4.properties.
- start-esup.sh, stop-esup.sh : scripts de lancement / arrêt
du serveur esup-portail ; ils peuvent être adaptés localement.
- ac-racine-cru.keystore : c'est un magasin de certificats qui contient
le certificat de l'autorité racine du CRU (pour les établissements
utilisant les certificats serveurs du CRU)
- scripts : contient des scripts utilitaires
- packages : répertoire, qui contient les 'sous-packages' qui
vont être installés : le serveur tomcat, la distribution uPortal
et les personnalisations esup-portail
- UpdateEsup : répertoire, qui contient les fichiers du sous-package
de personnalisation esup-portail. Il est essentiellement composé de
3 sous répertoires, Tomcat, uPortal, ROOT. Ces sous-répertoires
contiennent des fichiers (fichiers de propriétés, librairies,
sources, ...) qui seront déployés respectivement vers l'environnement
tomcat (server.root) ou vers la distribution uPortal (uportal.distrib) lors
du ant esup.init, et vers la racine de l'environnement exécutable lors
du uportal.deploy (esup.deploy/uPortal).
- Perso : répertoire, qui est également composé
des 3 sous répertoires Tomcat, uPortal et ROOT. Ces répertoires
sont vides lors de l'installation du package. Ils sont déployés
comme les sous-répertoire d'UpdateEsup.
En fait, l'emplacement de ce répertoire est maintenant paramétrable
(propriété esup.custom).
L'intérêt est de permettre aux établissements d'y mettre
leurs propres fichiers de configuration, sources, ... sans intervenir directement
sur les fichiers livrés avec le package.
Remarque : pour le bon fonctionnement du package, seuls les fichiers
properties suivants peuvent (et doivent) se trouver à la racine :
- esup-2.3.properties. Obligatoire, modifications autorisées.
- default.esup-2.3.properties. Obligatoire, modifications interdites
Autres répertoires créés par le package (suite à
ant esup.init)
Déploiement de tomcat (server.home)
C'est le répertoire dans lequel la procédure d'installation va
déployer le serveur tomcat. La procédure d'installation va supprimer
les applications d'exemples livrés avec la distribution tomcat.
En fait, le déploiement de ce répertoire (et les différents
paramètres liés) ne sera effectué que si le paramètre
server.deploy=true
Déploiement de l'environnement source d'uPortal (esup.distrib)
C'est le répertoire dans lequel la procédure d'installation va
déployer les sources d'uPortal, puis ultérieurement les personnalisations
liées à eSup-portail et aux directives du fichier esup-2.4.properties.
Déploiement des exécutables esup-portail (esup.deploy)
C'est le répertoire où seront déposés les fichiers
issus du déploiement esup-portail (lors du ant uportal.deploy). C'est
donc ce répertoire qui sera connu du moteur de servlet (tomcat) pour
l'exécution du portail.
En fait, le déploiement d'esup-portail se fait dans un sous-répertoire
nommé uPortal.
Installation et personnalisation
Ce paragraphe décrit de manière rapide le processus d'installation,
de paramétrage ; les paragraphes suivant détaillent les différents
paramètres ou options.
L'installation complète peut (et devrait) se faire depuis un compte
utilisateur non root. Il est bien sûr nécessaire que ce compte
ait un droit d'écriture ddans les différents répertoires
paramétrés.
- Décompresser le package dans le répertoire choisi ;
un répertoire est créé : uPortal-2.4-esup-xxx, où
xxx est le numéro de version ; on appellera ce répertoire la
'racine' du package (esup.root).
- cd uPortal2.4-esup-xxx
- Adapter le fichier esup-2.4.properties. C'est le principal travail
à effectuer. Ce fichier est décrit plus loin dans ce document.
- Faire ant esup.unzip : ceci décompacte les produits situés
dans le répertoire packages :
- le serveur tomcat (vers le répertoire server.home), si
server.deploy = true
- l'installation source uPortal (vers le répertoire esup.distrib)
- les librairies et personnalisations esup (vers le sous-répertoire
${esup.root}/UpdateEsup)
- Faire ant esup.init : recopie les librairies et personnalisations
esup vers l'installation source uPortal, puis exploite les paramètres
du fichier esup-2.4.properties pour mettre à jour les différents
fichiers de paramétrage uPortal et Tomcat
- Faire ant uportal.compile : compilation des sources java si nécessaire.
- Faire ant uportal.dbtest : teste et valide l'accès à
la base de données uPortal.
- Si le sgbd est mysql ou postgree, noter le "Database version"
(dans les première lignes du rapport), et mettre cette valeur complète
dans la propriété esup.db.db-version
- Si c'est un autre sgbd, voir pour editer manuellement le fichier dbloader.xml
- En cas de changements, refaire un ant esup.init pour répercuter
ceux-ci
- Faire ant esup.db.init : initialise la base uPortal, et déploie
éventuellement des canaux et fragments de base.
- Enfin, ant uportal.deploy : déploiement vers l'environnement
d'exploitation.
Un seul compte local est réellement utilisable au démarrage :
le compte admin (mot de passe admin).C'est le compe de l'administrateur
global d'esup-portail.
Lancement / arrêt de serveur
Deux scripts shell sont fournis, installés sous la racine du package
(esup.root) :
- start-esup.sh : permet de démarrer le serveur tomcat.
- stop-esup.sh : arrêt du serveur tomcat.
Remarques :
- Le moteur de servlet peut (et devrait) être lancé depuis un
compte non root ; pour celà, il est nécessaire que les ports
TCP ouverts par ce moteur (server.port.shutdown, server.port.http, server.port.jk)
soient supérieurs à 1024.
Ca ne pose pas de problème dans une configuration ou un serveur apache
est utilisé en frontal du moteur de servlets (via mod_jk1 ou mod_jk2),
ce qui est fortement conseillé.
- Par défaut, le serveur esup-portail authentifie CAS et avec la base
locale. Le compte d'administration est 'admin'. Il est possible de
se loguer avec ce compte, à l'aide d'un formulaire qui n'est pas visible
depuis la page du portail.
Cette page est accessible depuis un sous-répertoire 'private'
de l'URL du portail, donc à l'URL ${esup.host.https}/private/
Par exemple, si le portail est accessible à http://ent.univ.fr, la
page permettant de se loguer avec la base locale sera accessible à
https://ent.univ.fr/private
Propriétés du fichier esup-2.4.properties
Un fichier situé à la racine du package permet de paramétrer
l'ensemble de l'installation esup-portail : c'est esup-2.4.properties.
La prise en compte de modifications dans ce fichier nécessite un ant
esup.init, puis ant uportal.deploy, et enfin un redémarrage du serveur.
Ces propriétés supportent toutes des valeurs par défaut,
sauf la première
Paramètres de chemins file système
- java_home : le répertoire d'installation de la JVM.
- esup.root : c'est la racine du package. Par exemple, si le package
a été installé sous C:\esupdev, esup.root=c:/esupdev/esupdev-2.4
/home/esup/uPortal-${esup.distrib.version} par défaut
- esup.distrib : c'est l'emplacement source et de compilation de la
distribution esup-portail
/home/esup/uPortal par défaut
- esup.deploy : définit le répertoire de déploiement
d'exploitation de l'environnement esup-portail et des portlets éventuelles.
Le portail sera déployé dans un sous-répertoire uPortal
de esup.deploy, les portlets directement dans ce répertoire.
esup.deploy=/home/esup/webapps par défaut
- esup.custom : indique l'emplacement des personnalisations propres
au site (appelé répertoire Perso).
${esup.root}/Perso par défaut
- server.home : le répertoire d'installation du serveur tomcat
livré avec ce package, si server.deploy=true
/home/esup/Tomcat par défaut
- server.temp : c'est un répertoire temporaire du serveur, utilisé
par exemple lors des uploads de fichiers.
${server.home}/temp par défaut
- esup.log.file : nom du fichier de log uportal.
${esup.root}/portal.log par défaut
- esup.stats.file : nom du fichier de stats.
${esup.root}/stats.log par défaut
- esup.stats.recordSessions : C'est une propriété booléenne.
Si true, les informations d'ouverture / fermeture de sessions sont enregistrées
dans le fichier de stats.
true par défaut
- esup.stats.recordTargeted : C'est une propriété booléenne.
Si true, les informations d'activité des canaux sont enregistrées
dans le fichier de stats (lors de la fermeture de la session utilisateur).
Ces infos ne sont enregistrées que si esup.stats.recodSessions est
également à troue.
true par défaut
- esup.stats.fnames : contient la liste des 'fname' des canaux pour
lesquels on désire un suivi statistique.
C'est une liste de 'fname' séparés par le caractère 'virgule'
(,).
par exemple : esup.stats.fnames=esup-webdav,pers-esup-annu,esup-mailto
La valeur "all" active les statistiques se service pour tous les
canaux.
all par défaut
- esup.keystore : c'est le magasin de certificats utilisé par
tomcat pour valider ses accès https. Il doit au moins contenir un certificat
validant le serveur CAS.
${esup.root}/ac-racine-cru.keystore par défaut
A noter : un keystore est fourni avec ce package : ac-racine-cru.keystore
; il contient le certificat de l'ac-racine du CRU. Si vos certificats de serveurs
sont délivrés par le CRU, en particulier le certificat du serveur
CAS, vous pouvez utiliser ce fichier.
Paramètres http et ports TCP liés à esup-portail
Certaines de ces propriétés peuvent paraître redondantes
; il n'en est rien, certaines ne sont utiles que dans le cas d'un fonctionnement
en répartition de charge.
Afin de mieux comprendre le rôle de ces propriétés, on
résume ici les différentes mises en oeuvre possibles du portail
:
- Seul tomcat est utilisé pour délivrer le contenu ; il doit
donc implémenter le connecteur http tomcat.
- Un serveur apache est installé en frontal du serveur tomcat ; mod_jk2
est utilisé pour la communication frontal - tomcat
- répartition de charge (load-balancing), avec différentes options
:
- un seul frontal apache qui gère le load-balancing avec mod_jk2
- Un load-balancer qui distribue les requêtes http vers les serveurs
tomcat
- idem 2, mais avec un apache en frontal de chaque tomcat
Pour ce dernier cas, on distingue le host et l'url 'virtuels' ou publiques,
qui correspondent à l'url connue du public, du host et url 'réel'
qui correspondent au serveur réel qui délivre le contenu.
Parametres lies au serveur tomcat
- tomcat.port.shutdown : c'est le port de 'shutdown' de tomcat. A modifier
par exemple si plusieurs instances d'esup-portail tournent sur la même
machine.
8005 par défaut
- tomcat.port.http : c'est le port d'écoute du connecteur http
de tomcat. Si le fonctionnement est de type 'standalone', donc sans frontal
apache, ca sera le port d'accès au serveur esup-portail
8080 par défaut
- tomcat.port.jk : c'est le port d'écoute du connecteur JK2
de tomcat. Il sera utilisé par un éventuel frontal HTTP (apache,
par exemple, avec mod_jk)
8009 par défaut
- tomcat.http : C'est une propriété booléenne.
Si true, le connecteur http de tomcat est actif.
true par défaut
- tomcat.jk : C'est une propriété booléenne. Si
true, le connecteur jk de tomcat est actif.
true par défaut
Paramètres liés au host virtuel (url publique)
- esup.public.host : c'est le nom DNS d'accès au portail. A
CHANGER
ent.univ.fr par défaut.
- esup.public.proto : le protocole utilisé pour les accès
publics.
valeurs possibles : http ou https.
http par défaut
- esup.public.port : le port TCP pour les accès public au portail.
valeurs possibles : "" ou ":nnn". ex : ":8080",
ou ":8443"
Si valeur vide, sous-entend ":80" en http, ou ":443" en
https si l'accès normal au portail est en https
"" par défaut
- esup.public.uri : l'uri d'accès au portail
Si le portail est accessible à la racine du site, ne pas mettre "/"
; laisser vide
/uPortal par défaut
Remarque : L'url publique d'accès au portail se déduit
de ces 4 paramètres :
${esup.public.proto}://${esup.public.host}${esup.public.port}${esup.public.uri}
Paramètres liés au host réel
Ils sont utilisés lors d'accès https directs vers le serveur
réel, soit pour l'URL de callback CAS, soit pour le passage temporaire
en https
- esup.real.host : le nom DNS du serveur réel. Ne pas décommenter
si pas d'utilisation en load-balancing
${esup.public.host} par défaut
- esup.real.port.https. Le port TCP pour les accès https directs
au serveur réel
valeurs possibles : "" ou ":nnn". ex : ":8443"
Si valeur vide, sous-entend ":443" en https
"" par défaut
- esup.real.uri : l'uri d'accès au portail, par le serveur réel
en https.
Mêmes regles que esup.public.uri
${esup.public.uri} par défaut
Remarque : L'url d'accès https au serveur réel se déduit
de ces 3paramètres :
https://${esup.real.host}${esup.real.port.https}${esup.real.uri}
Paramètres liés à LDAP
Ce sont des paramètres liés à l'authentification LDAP
(si nécessaire), et à l'accès aux informations LDAP pour
constituer des groupes ou des attributs uportal issus de requêtes LDAP.
Pour le moment, les groupes LDAP ne sont pas traités
- esup.ldap.host, esup.ldap.port, esup.ldap.baseDN :
ce sont les informations nécessaires au bind LDAP
ldap.univ.fr, 389, "ou=People,dc=univ,dc=fr'
par défaut
- esup.ldap.bindDN, esup.ldap.bindPasswd : ces propriété
sont obligatoires, mais peuvent être laissées vides. Elles sont
utilisées si besoin d'un bind non anonyme lors de la récupération
des attributs LDAP liés à la personne.
"" et "" par défaut
- esup.ldap.groups.etu.formation : c'est le nom de l'attribut LDAP
qui permet de 'discriminer' les formations d'étudiants
etud-formation par défaut
Paramètres liés à CAS
Ce sont des paramètres liés à l'authentification CAS
- esup.cas.auth . booléen. Si true, l'authentification CAS est
activée.
A mettre impérativement à false si il n'y a pas de serveur
CAS opérationnel utilisable.
false par défaut
- esup.cas.proxy . booléen. Si la valeur est true, cette instance
de serveur esup-portail se comporte comme un proxy CAS. Il faut impérativement
dans ce cas que cette instance d'esup-portail puisse être accessible
en https, et que son certificat de serveur soir reconnu (ou l'autorité
de certification ayant validé le certificat) par le serveur CAS.
false par défaut
- esup.cas.host : c'est le nom DNS du serveur CAS
auth.univ.fr par défaut
- esup.cas.port.https. C'est le port d'acces TCP (necessairement https)
au serveur CAS
valeurs possibles : "" ou ":nnn". ex : ":8443"
si valeur vide, sous-entend ":443"
"" par défaut
- esup.cas.uri : l'uri d'acces au serveur CAS
ex : esup.cas.uri=/cas
si le serveur CAS est a la racine http, ne pas mettre '/' : laisser vide
"" par défaut
Et le paramètres suivants d'accès aux différents services
du serveur CAS.
Ils ne devraient normalement pas être modifiés.
L'uri réelle d'accès à un service CAS est en fait la concaténation
de ${esup.cas.uri} avec la propriété indiquée
- esup.cas.uri.login : URI de login CAS
/login par défaut
- esup.cas.uri.validate : URI de validation de ticket CAS
/serviceValidate par défaut
- esup.cas.uri.proxy : URI permettant de recuperer un proxy ticket
CAS
/proxy par défaut
et les URIs suivants à ajouter à l'URL du portail, liés
à l'authentification CAS ; a ne pas modifier
- esup.public.uri.login : URI utilisee pour le login dans le portail
/Login par défaut
- esup.real.uri.callbackCas : URI de callback (pour recuperation du
PGT)
/CasProxyServlet par défaut
Paramètres liés aux accès SGBD uportal
- esup.db.auth : booléen. Si a true, on utilise également
les comptes internes à la base uPortal (admin, par exemple)
N'est pas indispensable : le compte admin pourrait être un compte LDAP,
ou bien il est possible de mettre un compte issu de LDAP dans le groupe 'Administrateurs
uportal'.
true par défaut
- esup.db.persondirs.use : booléen. Utilise également
la base interne uPortal pour les informations d'attributs de personne.
false par défaut
- esup.db.username : c'est un nom d'utilisateur connu du SGBD, ayant
tous les droits dans la base décrite dans l'URL de connexion
sa par défaut
- esup.db.password : c'est le nom de passe de l'utilisateur précédant.
vide par défaut
- esup.db.jdbcDriverJar : c'est le fichier .jar driver jdbc du SGBD
utilisé. Ce driver doit se trouver dans le répertoire MajEsup/drivers.
Pour le moment, les drivers disponibles sont relatifs aux SGBD mysql, postgree,
le driver oracle n'étant pas distribuable en libre.
mysql-connector-java-3.0.10-stable-bin.jar par défaut
- esup.db.className : c'est la classe java correspondant au driver
jdbc
com.mysql.jdbc.Driver par défaut
- esup.db.url : c'est l'url jdbc de connexion.
jdbc:mysql://mysql.univ.fr/uportal par défaut
- esup.db.db-version : c'est la versin du serveur SGBD utilisé.
Indifférent pour hsql
A remplir obligatoirement pour mysql ou postgree. Récupérer
la valeur "Database version" lors du ant uportal.dbtest
4.0.18-max-log par défaut
Paramètres divers
- esup.multiservers : booléen. Si true, le fonctionnement multi-serveurs
est activé. Nécessaire dans un fonctionnement en load-balancing
false par défaut
- esup.webservices.axis : booléen. Si true, les librairies axis
permettant les webservices sont activées.
Le menu d'admin webservices est alors accessible à <portal-uri/services
false par défaut
- esup.webservices.axis.groups : booléen. Si true, le webservice
permettant d'exporter les groupes uPortal est activé.
false par défaut
- esup.host.logicalName : C'est un nom logique de l'instance d'uPortal.
Utilisé par exemple dans les logs pour les discriminer en fonction
de l'instance.
esup1 par défaut
- esup.render.columns : booléen. Si true, la navigation onglets
- colonnes est celle par défaut dans uPortal. Sinon, c'est un système
de menus / sous-menus alternatif.
Voir le document lié
à cette option.
N'est actif que si esup.env.esup-portail=true
true par défaut
- esup.session.lifetime : duree de la session esup-portail en minutes
30 par défaut
- esup.languages : les langues supportées par le portail.
ex : en_US,ja_JP,sv_SE,de_DE
fr_FR,en_US par défaut
- esup.pubchan : booléen. Si true, les canaux et les fragments
fournis avec la distribution sont automatiquement publiés, lors du
ant esup.db.init. Si false, ils ne le sont pas.
true par défaut
- server.deploy : booléen. Indique si le serveut Tomcat doit
être installé et paramétré lors de l'installation
du package.
Si false, le serveur Tomcat n'est pas supprimé lors du ant esup.cleanall
true par défaut
- esup.title.main : le 'title' html de la page esup-portail (en utf8
si accentués)
esup-portail par défaut
- esup.users.autocreate : booléen. si true, esup-portail crée
automatiquement dans sa base interne tout utilisateur qui a été
authentifié
true par défaut
- esup.userprefs.save : booléen. Indique si les preferences
utilisateurs doivent être sauvegardees a la fin de chaque session
true par défaut
- esup.log.size : la taille du fichier log, avant rotation
50000KB par défaut
- esup.log.level : le niveau de log (INFO, WARNING, DEBUG, ...)
INFO par défaut
- esup.stats.attributeType : c'est le nom de l'attribut uportal utilisé
pour discriminer les utilisateurs dans les stats.
eduPersonPrimaryAffiliation par défaut
- esup.stats.size : la taille du fichier stats, avant rotation
30000KB par défaut
Finalement, les paramètres à priori nécessaires à
coup sûr sont :
java_home, esup.root, esup.host.http, esup.public.host, esup.db.username, esup.db.password,
esup.db.url, esup.ldap.host, esup.ldap.port, esup.ldap.baseDN, esup.ldap.groups.etu.formation
Et certainement nécessaires si mysql ou postgree :
esup.db.db-version
Directives ant
Les différentes actions liées à ce package (en dehors
du lancement ou de l'arrêt du serveur) se font par l'intermédiaire
de l'utilitaire 'ant', lancé par la commande 'ant' suivie de paramètres.
L'exécution de ces directives doit se faire nécessairement depuis
la racine du package (esup.root).
Certaines directives sont directement issues de la distribution uPortal ; elles
sont préfixées par 'uportal'.
Les autres ont été créées spécifiquement
pour le package esup-portail ; elles sont préfixées par 'esup'.
Elles exploitent les paramétres écrits dans le fichier esup-2.4.properties.
Directives développées par esup-portail
ant esup.unzip
Comme indiqué précédemment, cette directive décompacte
les 'sous-packages' situés dans le répertoire packages.
A noter que Tomcat n'est déployé que si server.deploy=true
ant esup.init
Cette directive applique la personnalisation esup-portail au package.
- nettoyage éventuelle d'un 'ant esup.init' précédent
- recopie de UpdateEsup/Tomcat vers l'environnement Tomcat (si server.deploy=true)
- recopie de UpdateEsup/uPortal vers l'environnement de la distribution uPortal
- Même opération pour Perso/Tomcat et Perso/uPortal
- Application des paramètres du fichier esup-2.4.properties vers les
environnements Tomcat (si server.deploy=true) et uPortal
Doit être suivi d'un ant uportal.deploy et d'une relance du serveur pour
prise en compte.
A noter que l'environnement Tomcat n'est impacté que si server.deploy=true
ant esup.cleanall
Cette directive supprime les installations ou modifications faites par l'installation
précédente du package sauf :
- Le répertoire d'exécution du portail (esup.deploy)
- Le répertoire d'installation Tomcat, si server.deploy=false
Ne supprime pas l'environnement d'exécution (esup.deploy)
ant esup.db.init
Cette directive écrase et réinitialise la base uPortal. Si esup.pubchan
= true (par défaut), des canaux et des fragments 'de base' sount également
publiés ; ce sont les canaux décrits dans les fichiers xml présents
dans properties/chanpub, et le fichier de fragment properties/al/esup-fragments.xml
ant esup.users.ldapadd
Cette directive permet de 'précharger' les comptes utilisateurs uPortal
à l'aide de comptes issus d'un annuaire LDAP.
Doit être lancée avec les paramètres nécessaires
aux accès LDAP :
- LdapURL : obligatoire . l'URL d'accès au serveur LDAP
- LdapFilter : obligatoire. le filtre LDAP à appliquer
- LdapLoginID : facultatif. Un Distinguish Name (DN) en cas de bind non anonyme
- LdapPass : facultatif. Le mot de passe en cas de bind non anonyme.
Exemples :
esup.users.ldapadd -DLdapURL="ldap://ldap.univ.fr/dc=univ,dc=fr"
-DLdapFilter="(&(objectclass=inetorgperson)(cn=a*))"
esup.users.ldapadd -DLdapURL="ldap://ldap.univ.fr:392/dc=univ,dc=fr"
-DLdapFilter="(&(objectclass=inetorgperson)(cn=a*))"
-DLdapLoginID=uid=admin,dc=univ,dc=fr -DLdapPass=password
Il est possible de relancer régulièrement cette commande afin
de créer les comptes uPortal correspondant aux nouveaux comptes LDAP
; les anciens comptes ne sont pas impactés.
Cette commande est très utile en cas d'utilisation de l'option esup.users.autocreate=false,
ce qui permet de limiter la population ayant accès au portail.
ant esup.groups.load
Cette directive permet de gérer les groupes uportal à l'aide
d'un fichier de configuration xml.
Par défaut, le fichier utilisé est properties/groups/GroupLoad.xml
Voir la documentation de cet utilitaire.
Il supporte le paramètre dataFile, qui permet d'utiliser un autre
fichier de configuration.
Exemple :
ant esup.groupload -DdataFile=/properties/groups/esupGroupLoad.xml
ant esup.groups.perm.load
Cette directive permet de gérer les permissions liées aux groupes
uportal à l'aide d'un fichier de configuration xml.
Par défaut, le fichier utilisé est properties/groups/GroupPermLoad.xml
Il supporte le paramètre dataFile, qui permet d'utiliser un autre
fichier de configuration.
Exemple :
ant esup.groups.perm.load -DdataFile=/properties/groups/GroupPermLoadSample.xml
Directives liées à la distribution uportal
Ce sont les directives qu'on peut lancer habituellement depuis la distribution
uPortal. Le principal intérêt de les reprendre est d'éviter
d'avoir à se déplacer dans le répertoire de distribution
uportal.
Un autre intérêt concerne les directives qui impactent la base
uPortal (db, dbtest, initportal, ...) : normalement, il est nécessaire
de désactiver l'utilisation jndi dans uportal.properties pour le faire.
Ici, ce n'est plus nécessaire.
Le nom de ces directives est le même que les directives fournies avec
la distribution uPortal, en les préfixant de 'uportal.'.
Ainsi, les directives suivantes sont fournies :
uportal.projecthelp, uportal.all, uportal.clean, uportal.compile, uportal.deploy,
uportal.dist, uportal.initportal, uportal.db, uportal.dbtest, uportal.pubchan,
uportal.pushfragment, uportal.deployPortletApp, uportal.dbunload, uportal.javadoc,
uportal.md5passwd, uportal.deluser
Remarque : ne plus utiliser la directive uportal.initportal. C'est la directive
esup.dn.init qui doit être utilisée.
En pratique, les directives uPortal dont vous aurez besoin sont :
- ant uportal.compile : compilation des sources, et recopie dans uPortal_2-4-x-quick-start/uPortal_rel-2-4-x/build
- ant uportal.deploy : compilation si nécessaire des sources
'fraiches', et recopie dans l'environnement d'exécution tomcat (uPortal_2-4-x-quick-start/webapps/uPortal)
- ant uportal.dbtest : test de la connctivité à la base
- ant uportal.pubchan : permet de publier d'exécuter un/des
fichiers de publication de canaux se trouvant sous uPortal_2-4-x-quick-start/uPortal_rel-2-4-x/properties/chanpub/
- ant uportal.pubfragments : permet de oublier un fichier de publication
de fragments se trouvant sous uPortal_2-4-x-quick-start/uPortal_rel-2-4-x/properties/al/
- ant uportal.md5passwd : permet de créer un utilisateur uPortal
local, ou de modifier son mot de passe.
- ant uportal.deluser : permet de supprimer un utilisateur uportal.
Utilisation de l'arborescence Perso
Le but est de permettre de modifier des fichiers de configuration, de source,
... tout en laissant la possibilité de faire ensuite une mise à
jour du package, ou une nouvelle installation en récupérant facilement
les modifications locales.
L'emplacement de ce répertoire est maintenant paramétrable (propriété
esup.custom).
L'arborescence Perso est découpée en 3 sous-répertoires,
Tomcat, uPortal et ROOT, vides initialement. Elle est donc organisé comme
le répertoire UpdateEsup.
Lors d'un ant esup.init, les arborescences UpdateEsup/Tomcat, UpdateEsup/uPortal
sont recopiés dans l'environnement source uPortal, puis l'arborescence
Perso ; enfin, les personnalisations sont appliquées dans les fichiers
de configuration.
Et Lors d'un ant uportal.deploy, l'arborescence UpdateEsup/ROOT est recopiée
à la racine de l'environnement d'exécution du portail.
Les fichiers de personnalisations qui seraient propres à l'établissement
(sources java, fichiers de config, fichiers Tomcat, lgos, ...), sont à
placer dans l'arborescence Perso.
Ceci permettra toujours la modification des fichiers de properties, voire de
faire une mise à jour de votre package, ceci sans perdre les personnalisations
non prévues dans le package.
Conseils d'utilisation
Mots de passe initiaux
Il est impératif de changer le mot de passe de l'administrateur local
(admin) très rapidement.
En faire de même pour le compte demo, qui est un 'modèle' pour
les comptes qui seront créés dynamiquement.
Paramètres JVM et Tomcat
Les fichiers scripts proposés, et le paramétrage de tomcat ne
sont pas optimisés.
Ils permettent de démarrer rapidement un environnement de semi-production.
Il est nécessaire de paramétrer au plus près la JVM (occupation
mémoire, fonctionnement du garbage collector, ...) et tomcat (utilisation
des pools de connexion, ...) en fonction de votre exploitation.
Configuration Tomcat
Il est plus que probable que chaque établissement aura à personnaliser
son environnement tomcat ; et aura à coeur que l'installation tomcat
se soit pas perturbée par des modifications de paramètres liés
à esup-portail. Donc, il est fortement conseillé de mettre la
propriété server.deploy à la valeur false à la suite
d'une première installation.
Applications admin et manager de tomcat
Lors de l'installation du package, ces applications livrées avec tomcat
sont actives.
Elles permettent d'administrer le serveur tomcat depuis un navigateur.
C'est un problème de sécurité potentiel.
Il est à la charge de l'établissement de les sécuriser,
voire de les supprimer.
Modifier en particulier le fichier tomcat-users.xml afin de changer les comptes
ayant des accès à ces applications.
Personnalisations
Ce package est destiné à une première installation d'un
environnement de production esup-portail.
Les paramètres prévus dans le fichier esup-2.4.properties, et
les différents fichiers proposés par esup-portail seront sans
doute insuffisants pour une personnalisation plus poussée.
Par exemple, lors de l'adaptation / création d'un nouveau skin, de logos,
voire de modifications de sources uPortal ou esup-portail,...
Il est donc important de mettre les fichiers 'locaux' dans l'arborescence
Perso : ceci permet d'une part, de bien discerner les personnalisations
locales par rapport à l'environnement initial, et d'autre part, de pouvoir
faire des mises à jour du package tout en pouvant les ré-appliquer
ultérieurement.
