|
Ce document décrit comment installer et utiliser le package 'environnement de prise en main esup-portail'. |
| Dates de modification | ||
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Ce document décrit comment installer et utiliser le package esupdev2.5 : 'environnement de prise en main esup-portail'. Cet environnement peut être utilisé à des fins de test esup-portail, ou de mise en oeuvre rapide d'un environnement de développement, ceci depuis un système windows ou linux.
Il est valable pour les versions de packages à partir de 2.5-esup-2.
Pour les versions précédentes, consulter l'ancienne doc.
Il installe à la fois le serveur Tomcat, un serveur HSQL, la distribution uPortal et des apports esup-portail. Il s'appuie sur l'installation 'quick-install' d'uportal V2.5, et ajoute la 'couche' esup-portail.
Il livre donc un environnement complet du portail, comprenant les différentes librairies d'accès au SGBD, à LDAP, et d'interfacage avec le mécanisme de SSO CAS.
Il ne livre pas les différents canaux esup-portail, à installer indépendamment .
La base liée à ce package peut être initialisée de 2 manières : avec un environnement qui est celui d'esup-portail, out avec l'environnement de base uPortal.
Un fichier de propriété unique permet de paramétrer delà d'un manière simple.
Il est possible de l'utiliser en autonome, il suffit au minimum d'avoir installé préalablement un JDK 1.5. La mise en oeuvre est donc très rapide.
Le package esupdev2.5 est très proche du package d'installation de l'environnement de production esup-portail ; seules les différences entre les 2 packages seront décrites ici.
En plus d'une distribution quick-install 2.5 d'uPortal, ce package propose :
accès SGBD : possiblité d'utiliser simplement différents SGBD comme base uportal
CAS : les différentes librairies liées au SSO CAS sont incluses. Si le serveur CAS utilise un certificat du CRU, le certificat de l'ac-racine est déja inclus dans la distribution, et tomcat est paramétré avec ce certificat.
Authentification : il est paramétré pour authentifier de base avec CAS ou la base locale. Une authentification LDAP est également possible.
Paramétrage simple des emplacements file-système, les urls des serveurs, ...
Fonctionnement et procédures identiques sous Windows et Linux.
Possibilité d'utiliser très simplement un frontal apache pour les différentes machines de développement
Centralisation des mises à jour : les paramètres essentiels figurent dans un seul fichier. Les différentes commandes liées à la personnalisation, la compilation, le lancement ou l'arrêt du serveur sont similaires et exécutées depuis la racine du package.
interfaçage aisé avec l'environnement de développement 'eclipse'
Skin : un skin au look esup-portail est inclus
navigation : une navigation alternative par menus et sous-menu est disponible en option
Base : la base peut être initialisée avec l'environnement initial uPortal, ou avec un environnement esup-portail (canaux d'exemple exclus, look esup-portail, groupes conforme à l'environnement esup-portail, ...)
La racine du package est : esupdev-2.5-esup-x. Sous cette racine se trouvent différents fichiers ou répertoires. Les principaux fichiers sont :
un document texte qui décrit le package, et résume les procédures d'installation et d'utilisation.
c'est le fichier utilisé lors des différentes directives ant. A ne pas modifier.
c'est un fichier de propriétés qui paramètre le fonctionnement de l'installation. A ne pas modifier.
c'est le fichier de paramétrage du package. Toutes les personnalisations propres à esup-portail sont paramétrés depuis ce fichier
c'est un fichier de paramétrage auxilliaire qui accepte les même propriétés que le fichier précédent. Il est livré vide.
Les directives présentes dans custom.properties ont prédominance sur celles d'esup.properties.
L'intérêt : avoir par exemple un fichier esup.properties propre à un établissement (paramétrages LDAP, CAS, ...), et les quelques informations liées à la personnes (accès SGBD, ...) dans le fichier custom.properties, ceci dans le cadre d'essais ou de développements.
ant, start-esup, stop-esup, env, avec l'extension .sh pour l'environnement linux, et .cmd ou .bat sous Windows.
Et les sous répertoires de premier niveau :
c'est équivalent à une distribution quick-install d'uportal 2.5-x.
des utilitaires divers
contient des fichiers qui vont écraser les fichiers similaires de la distribution uPortal initiale lors de la personnalisation, ou apporter de nouveaux fichiers à la racine d'exécution du portail.
Il contient donc d'éventuels patchs relatifs aux sources uportal, des librairies, sources, skins, ... supplémentaires propres à esup-portail.
c'est une arborescence similaire à UpdateEsup (en fait, l'emplacement de ce répertoire est maintenant paramétrable, à l'aide de la propriété esup.custom)
Il contient 3 répertoires (comme UpdateEsup et ClearEsup) : ROOT, Tomcat et uPortal; ces répertoires sont livrés vides. Il est possible d'y ajouter des fichiers qui seront recopiés dans l'arborescence finale, afin de personnaliser.
Seul ce dernier répertoire ne devrait être modifié par les utilisateurs
On suppose ici une installation sous Windows, dans le répertoire C:\esupdev. La procédure est quasiment identique sous linux (à l'extension des scripts près).
On suppose qu'un JDK 1.5 est déja installé.
si on ne désire pas utiliser la distribution HSQL incluse, il faudra au préalable créer la base uPortal (ant esup.db.init).
On suppose ici une installation sous Windows, avec la JVM installée dans \jdk1.5 et ce package dans \esupdev.
Décompresser le package dans le répertoire choisi (ici, C:\esupdev) ; un sous-répertoire est créé : esupdev-2.5-esup-x ; il contient l'arborescence décrite ci-dessus.
cd esupdev-2.5-esup-x . On appellera ce répertoire la 'racine' du package (esup.root).
Sous linux, faire chmod 755 *sh
Adapter le fichier script ant (.bat ou .sh) ; normalement, les 2 variables d'environnement JAVA_HOME et ESUP_DEV.
Adapter le fichier esupdev-2.5.properties. C'est le principal travail à effectuer. Ce fichier est décrit plus loin dans ce document. 2 options principales sont possibles :
initialiser la base et le look avec un environnement esup-portail : propriété esup.env.esup-portail=true.
Il faut avoir une connaissance préalable du fonctionnement d'uPortal, en particulier dans la gestion des groupes et des permissions.
initialiser la base et le look avec l'environnement par défaut uPortal : propriété esup.env.esup-portail=false
A choisir pour une prise en main.
Eventuellement, enrichir le fichier custom.properties
Lancer ant esup.init (sous linux : ./ant.sh esup.init) pour répercuter les personnalisations dans l'environnement uportal.
Lancer ant uportal.compile : compilation (si nécessaire) des source uPortal
Lancer ant uportal.dbtest : ceci permet de tester la connectivité à la base SGBD du portail.
Si le sgbd est hsql, rien à faire
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 editer manuellement le fichier dbloader.xml
En cas de changements, refaire un ant esup.init pour répercuter ceux-ci
La première fois, faire ant esup.db.init : initialise la base en fonction des propriétés esup.env.esup-portail, esup.pubchan.
ATTENTION : ceci écrase la base uPortal ; ce n'est donc à faire que si on veut réinitialiser la base.
Faire ant esup.deploy : compilation des sources java si nécessaire, et déploiement vers l'environnement Tomcat
Il est possible de passer alternativement de la base uportal à la base esup-portail :
modifier la propriété esup.env.esup-portail
ant esup.init
ant esup.deploy
ant esup.db.init (nécessaire pour le changement d'environnement)
start-esup
Ce sont des comptes préparamétrés dans la base locale uPortal
les comptes suivants sont disponibles (le mot de passe est identique au login) :
admin (droits d'administration globale)
demo (compte dont héritent les nouveau comptes créés)
guest (utilisateur anonyme. Compte utilisé en non authentifié)
faculty
staff
student
Seuls les comptes admin, demo, guest sont valides.
Le lancement du serveur peut se faire de 2 manières :
start-esup (.cmd ou .sh)
ant tomcat.start
La seconde méthode peut être utile dans le cas d'utilisation de l'environnement de développement éclipse L'arrêt du serveur peut également se faire de 2 manières :
stop-esup
ant tomcat.stop
Note
pour les personnes désirant utiliser la base hsql, il est nécessaire de la lancer auparavant : ant hsql.start
Les directives sont identiques à celles du package de production esup-portail, aux différences suivantes près.
Se reporter à la documentation de ce package.
Arrêt / relance du serveur tomcat
Pour l'utilisation éventuelle du serveur HSQL distribué dans le package.
Les propriétés sont identiques à celles du package de production esup-portail, aux différences suivantes près.
Se reporter à la documentation de ce package.
Note
tous les séparateurs de répertoire utilisent le caractère '/', même sous Windows. Sous windows, et pour les chemins absolus, toujours préciser le nom de lecteur (ex : c:/esupdev).
propriété booléenne. Si false, propose l'environnement de base uportal, très permissif. Si true, propose l'environnement esup-portail
Défaut : false
C'est une propriété booléenne (false ou true) . Si true, l'authentification LDAP est activée. (A noter que l'authentification LDAP n'est pas prévue dans la distribution finale d'esup-portail).
Défaut : false
C'est une propriété booléenne. Si true, LDAP est utilisé pour lier des attributs LDAP aux attributs des utilisateurs esup-portail (voir le fichier personDirectory.xml).
Défaut : true
permet d'activer la gestion de groupes uPortal issus de LDAP. n'est utilise que si esup.ldap.persondirs.use=true
Défaut : true
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.
Défaut : false.
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.
Défaut : false.
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.
Défaut : true
booléen. si true, force tomcat à recharger le contexte esup-portail si un fichier a été changé dans l'environnement d'exploitation.
Utile uniquement en développement, sinon, charge inutilement le serveur de servlets.
Défaut : true
booléen. utilisation ou non des portlets exemples livrées avec uPortal.
Défaut : false
Se reporter à la documentation du package esup-portal.
Comme indiqué précédemment, le chargement de la base esup-portail (ant esup.db.init, avec esup.env.esup-portail à true) met le portail dans un environnement proche de celui d'exploitation.
En particulier, dans cet environnement, le compte 'demo' dont héritent les comptes uPortal créés n'appartient à aucun groupe ; il n'a donc aucun droit.
Le seul compte utilisable au démarrage est le compte admin.
Il faut donc que vous mettiez les nouveaux comptes créés dans un / des groupes uPortal afin qu'ils puissent disposer de certains droits.
Ceci est fait automatiquement par défaut si vous activez l'utilisation des groupes LDAP, et si votre annuaire est compatible supann : la distribution utilise alors l'attribut LDAP 'eduPersonnAffiliation' pour mettre automatiquement le compte créé dans un des groupes 'Personnels', 'Etudiants', ou 'Invites'.
Sinon, en développement, il faut vous loguer une première fois avec un compte authentifié (CAS ou LDAP), afin de vous faire 'connaitre' du portail.
Ensuite, se déloguer et se reloguer en admin, et ajouter ce compte comme membre d'un des groupes existants (de préférence personnel ,etudiant, ou invité, pour ne disposer que des droits minimum).
Des logs sont disponibles :
Dans tomcat/logs. En particulier, si problème d'accès https, contrôler les fichiers catalina.out et localhost.200x-mm-jj.log
sous la racine de l'installation, le fichier portal.log : ce sont les logs écrites par l'application uPortal et les différents canaux. S'y référer en cas de problèmes.
De base, la log uPortal est écite en mode 'INFO' ; il est possible de la mettre en mode 'DEBUG' pour plus d'information, mais ce dernier mode est extrêment bavard.
sous la racine de l'installation, le fichier stats.log. en fait, ce n'est pas un fichier de log à proprement parlé, mais un fichier contenant les statistiques d'utilisation du portail.
Le SGBD utilisé doit supporter les transactions.
En particulier, pour mysql, il faut utiliser des tables bdb ou innodb
Il est possible de ré-appliquer plusieurs fois la directive ant esup.init. Ne pas oublier de faire suivre d'un ant esup.deploy et d'un arrêt - relance de tomcat
Le package permet de fonctionner avec un serveur apache en frontal http, et mod_jk. Il est possible dans ce cas de prévoir un environnement de développement collectif au sein d'une université, avec un frontal apache accessible en http et https et un certificat reconnu du serveur CAS, puis de déporter des répertoires virtuels vers chaque machine de développement.
La contrainte est que le nom de répertoire virtuel du serveur apache frontal pour un utilisateur soit identique à l'URI local du serveur esup-portail (directive esup.public.uri). Ainsi, chaque environnement de développement se comporte comme un proxy CAS, sans soucis de certificats.
Un fichier CHANGELOG.txt est maintenu à la racine du package. Tout changement important, en particulier ceux qui concernent le paramétrage des fichiers properties ou la base uPortal sera précédé de la chaine suivante : '****'.