Space Details Key: MU Name: Projet uportal-esup Description: Le portail Creator (Creation Date): jmarchal (May 27, 2008) Last Modifier (Mod. Date): paubry (May 27, 2008) Available Pages Documentation Package 01 - Organisation 02 - Tâches ANT 04 - Configuration 01 - build.properties 02 - config.properties 03 - custom.properties 05 - Installation 06 - Conseils d'utilisation 07 - Personnalisations Document generated by Confluence on Jun 10, 2008 08:53 Page 1
Documentation Package This page last changed on Jun 03, 2008 by jmarchal. Cette partie concerne la documentation l'utilisation du package en lui même. Ce document décrit l'installation et le paramétrage du package du socle 'esup-portail' issu de la version 2.6 d'uportal. Le package contient l'intallation d'un serveur Tomcat (uniquement pour le package de développement), de la distribution uportal 2.6 et des librairies et personnalisations propres à l'environnement esup-portail. 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. On distingue 2 packaging différents : uportal-esup : package de production contenant la distribution uportal esupdev : package de développement contenant : la distribution uportal tomcat hsql ant Attention Cette documentation est valable pour les distributions - esupdev-2.6-esup-2.x.y - esup-2.6-esup-2.x.y Document generated by Confluence on Jun 10, 2008 08:53 Page 2
01 - Organisation This page last changed on May 28, 2008 by vrepain. Organisation file system de base C'est l'organisation des dossiers et fichiers suite au décompactage du paquet Esup : esup-2.6-esup-2.x.y contribs [...] custom uportal Tomcat logs [...] packages [...] resources [...] update [...] build.sample.properties config.sample.properties build.xml CHANGELOG ant.[sh cmd ] Avec : contribs : Dossier contenant diverses contributions. Ces contributions ne sont pas déployées automatiquement : vous devez les mettre vous-même dans votre dossier custom. custom : Dossier utilisé pour la personnalisation du portail : Vous pouvez y déposer vos propres fichiers de configuration, sources, feuilles de transformation, feuilles de styles, etc. Ces fichiers remplaceront ceux d'uportal et du dossier update lors du déploiement. Pour chaque fichier, vous devez respecter l'arborescence des dossiers dans lesquels il doit être déposé (exemple : Une personnalisation de persondirectory.xml sera placée dans custom/uportal/properties/ persondirectory.xml). Le dossier Tomcat n'est utilisable que dans le package esupdev. logs : Dossiers des logs par défaut packages : Dossier ou vont être stockés les distributions (compressées) des produits tiers téléchargés avec ant getcomponents (uportal, Ant, Tomcat, HSql...) ressources : Dossier contenant des fichiers nécessaire au fonctionnement du package. update : Dossier contenant les personnalisations Esup. Les sous-dossiers contiennent des fichiers (fichiers de propriétés, librairies, sources,...) qui seront déployés vers les sources uportal (esup.sources) lors du ant init, ou vers l'environnement tomcat (package esupdev uniquement) et la racine de l'environnement exécutable (esup.deploy) lors du ant deploy. Ne pas modifier le contenu de ce répertoire. build.sample.properties : Fichier d'exemple de configuration du fonctionnement du package. A recopier en build.properties et adapter au minimum le paramètre java_home. config.sample.properties : Fichier d'exemple de configuration des distribution (uportal). A recopier en config.properties et à adapter. build.xml : Fichier servant à ant CHANGELOG : Fichier qui recense toute les changements dans le package ant.[sh cmd] : Fichier de lancement des commandes ant. Organisation file system après une première utilisation esup-2.6-esup-2.x.y contribs [...] custom uportal Document generated by Confluence on Jun 10, 2008 08:53 Page 3
Tomcat logs last-ant-deploy-call.txt last-ant-init-call.txt [...] packages [...] Portail Ant-X.X.X Hsqldb-X.X.X.X Tomcat-X.X.X uportal_rel-x.x.x webapps resources [...] tmp update [...] build.sample.properties config.sample.properties build.xml CHANGELOG ant.[sh cmd ] env.[sh cmd ] start-esup.[sh cmd ] stop-esup.[sh cmd ] esup-portail.keystore On retrouve donc de nouveau : logs/last-ant-init-call.txt : Fichier trace du dernier ant init fait logs/last-ant-deploy-call.txt : Fichier trace du dernier ant deploy fait Portail/Ant-X.X.X : Dossier de distribution de Ant après ant unzip Portail/Hsqldb-X.X.X.X : Dossier de distribution Hsql après ant unzip (uniquement dans esupdev) Portail/Tomcat-X.X.X : Dossier de distribution Tomcat après ant unzip (uniquement dans esupdev) Portail/uPortal_rel-X.X.X : Dossier de distribution uportal après ant unzip Portail/webapps : Dossier contenant le portail compilé après ant deploy. C'est le dossier qui sera connu du moteur de servlet (tomcat) pour l'exécution du portail. Le déploiement du portail se fera dans un sous-répertoire nommé uportal, celui des éventuels portlets dans d'autres sous-répertoires dédiés. tmp : Dossier temporaire utilisé lors de la construction du package env.[sh cmd] : Script d'environnement esup start-esup.[sh cmd] : Script de démarrage stop-esup.[sh cmd] : Script d'arrêt esup-portail.keystore : keystore esup (cru) Document generated by Confluence on Jun 10, 2008 08:53 Page 4
02 - Tâches ANT This page last changed on May 29, 2008 by jmarchal. Liste des tâche ant du package : Error formatting macro: toc: java.lang.nullpointerexception init getcomponents unzip deploy db.test db.init db.unload db.unloadall clean undeploy hsql.start Nom de la tâche Description Exemple Lance un initialisation du portail ant.sh init (copie les updates, les customs, etc) Va chercher les distributions ant.sh getcomponents (compressé) des package dépendants (uportal, Ant, etc..) Décompresse les packages ant.sh unzip dépendants Déploie le portail dans le webapps ant.sh deploy Teste la connexion à la base de ant.sh db.test données Vide et remplie la base de données ant.sh db.test avec les informations esup-uportal (demande une confirmation) Décharge une table de la base de ant.sh db.unload - données Dtablename=up_channel -Dxmlfile=properties/db/ Décharge la totalité de la base de données Nettoie le répertoire de build du package Supprime l'ancien déploiement uportal Demande de confirmation Démarre le serveur Hsql intégré dans les package esup-uportal (uniquement disponible dans esupdev) Ctrl + C pour arrêter up_channel_backup.xml ant.sh db.unloadall - Dxmlfile=properties/db/ backup.xml ant.sh clean ant.sh undeploy ant.sh hsql.start Document generated by Confluence on Jun 10, 2008 08:53 Page 5
tomcat.start chan.pub chan.export group.load perm.load layout.import layout.export user.add user.del users.del users.ldap.add Démarre le serveur Tomcat intégré dans le package esup-uportal (uniquement disponible dans esupdev) Ctrl + C pour arrêter Publie la définition d'un ou de tout les canaux dans la base de données du portail Export la définition de tous les canaux du portail sous forme de fichier xml Charge des groupes dans la base uportal a partir d'un fichier XML Charge des permissions dans la base uportal à partir d'un fichier XML Importe un ou tous les fichiers XML représentant un environnement utilisateur. Les fichiers doivent se trouver dans /properties/layouts Exporte un environnement utilisateur sous forme de fichier XML Les fichiers seront stockés dans / properties/layouts Ajoute un utilisateur dans la base uportal Demande un mot de passe ant.sh tomcat.start ant.sh chan.pub -Dchan.pub=all ant.sh chan.pub -Dchan.pub=moncanal.xml ant.sh chan.export - DchannelDir=properties/ chanpubbackup ant.sh group.load - DdataFile=properties/groups/ GroupLoad.xml ant.sh perm.load - DdataFile=properties/groups/ GroupPermLoad.xml ant.sh layout.import - Dusername=all ant.sh layout.import - Dusername=username ant.sh layout.export ant.sh user.add -Dusername=titi Supprime un utilisateur de la base ant.sh user.del -Dusername=titi uportal Supprime une liste d'utilisateur ant.sh users.del -Dfilename=/tmp/ de la base uportal par rapport todel.txt a un fichier plat (une linge par utilisateur = login) Ajoute des utilisateurs dans le portail isssue d'une requête LDAP ant.sh users.ldap.add \\\\\\\\\\\\\ -DLdapURL="ldap:// ldap.univ.fr:392/dc=univ,dc=fr" \\ \\\\\\\\\\\ - DLdapFilter="(&(objectclass=inetorgperson) (cn=a*))" \\\\\\\\\\\\\ - DLdapLoginID="uid=admin,dc=univ,dc=fr" \\\\\\\\\\\\\ -DLdapPass="XXXXX" portlet.deploy Déploie une ou toutes les portlets ant.sh portlet.deploy - DportletApp=all ant.sh portlet.deploy - properties.debug Affiche la valeur courante de toutes les propriétés de configuration du package DportletApp=/tmp/myPortlet.war ant.sh properties.debug Document generated by Confluence on Jun 10, 2008 08:53 Page 6
04 - Configuration This page last changed on May 29, 2008 by jmarchal. On distingue 3 fichiers de configuration du package : build.properties : fichier contenant les propriétés de déploiement du portail config.properties : fichier contenant les propriétés de configuration du portail custom.properties : fichier prenant le dessus sur le build.properties et le config.properties. ce fichier vous permet de spécifier des options contenu dans le build et la config. Document generated by Confluence on Jun 10, 2008 08:53 Page 7
01 - build.properties This page last changed on Jun 05, 2008 by vrepain. Error formatting macro: toc: java.lang.nullpointerexception Fichier build.properties java_home=/usr/java/jdk1.5 # CURRENT FOLDER esup.root=${basedir.conv} devel.mode=false esup.base=${esup.root}/portail esup.sources=${esup.base}/uportal_rel-${uportal.ver} esup.deploy=${esup.base}/webapps esup.build=${esup.sources}/build server.home=${esup.base}/tomcat-${tomcat.ver} server.temp=${server.home}/temp esup.custom=${esup.root}/custom esup.update=${esup.root}/update esup.resources=${esup.root}/resources esup.packages=${esup.root}/packages esup.tmp=${esup.root}/tmp config.file=${esup.root}/config.properties Avec : Variable Description Exemple Modifiable Document generated by Confluence on Jun 10, 2008 08:53 Page 8
java_home esup.root devel.mode esup.base esup.sources esup.deploy esup.build server.home server.temp esup.custom esup.update esup.resources esup.packages esup.tmp config.file Le chemin où est installé le JDK Détermine automatiquement l'endroit ou se trouve le package Sélecteur qui permet de savoir au package si c'est un package esupdev ou esup Chemin par défaut ou le portail et toutes ses composantes seront installés Emplacement où seront décompressés les sources uportal Dossier où sera déployé le portail java_home=/usr/java/ jdk1.5 java_home=c:\jdk1.5.0 esup.root= ${basedir.conv} devel.mode=true devel.mode=false esup.base=${esup.root}/ Portail esup.base=/home/esup esup.sources= ${esup.base}/uportal_rel- ${uportal.ver} esup.sources=/home/ esup/src/uportal_rel- ${uportal.ver} esup.deploy= ${esup.base}/webapps esup.deploy=/home/esup/ webapps Dossier où sera compilé le esup.build= portail avant deploiement ${esup.sources}/build Emplacement ou se server.home= trouve Tomcat ${esup.base}/tomcat- Dans le package esupdev, ${tomcat.ver} emplacement où sera server.home=/usr/local/ décompressé Tomcat Tomcat-${tomcat.ver} Dossier temporaire de Tomcat Dossier contenant vos personnalisations Dossier contenant les personnalisation Dossier contenant des ressources propres au package Dossier contenant les distributions compressées des produits tiers (uportal, etc.) server.temp= ${server.home}/temp esup.custom= ${esup.root}/custom esup.custom=/home/ esup/moncustom esup.update= ${esup.root}/update esup.resources= ${esup.root}/resources esup.packages= ${esup.root}/packages OUI NON NON OUI OUI OUI NON OUI OUI OUI NON NON NON Dossier temporaire du package esup.tmp=${esup.root}/ tmp NON Fichier de configuration duconfig.file=${esup.root}/ OUI portail config.properties config.file=/home/esup/ maconfig.properties En toute logique lors de la configuration vous devez changer : 1. java_home 2. esup.sources, esup.deploy (ou alors esup.base si vous voulez tout mettre dans le même dossier) 3. server.home Document generated by Confluence on Jun 10, 2008 08:53 Page 9
02 - config.properties This page last changed on Jun 05, 2008 by vrepain. Error formatting macro: toc: java.lang.nullpointerexception Fichier config.properties # tomcat tomcat.update.conf=true tomcat.update.lib=true tomcat.reloadable=true tomcat.port.shutdown=8005 tomcat.port.http=8080 tomcat.port.jk=8009 # URL esup.public.host=localhost esup.public.proto=http esup.public.port= esup.public.uri=/uportal esup.public.finalurl=${esup.public.proto}:// ${esup.public.host}${esup.public.port}${esup.public.uri} esup.real.host=${esup.public.host} esup.real.uri=${esup.public.uri} esup.real.port.https= esup.real.https.finalurl=https://${esup.real.host}${esup.real.port.https}${esup.real.uri} # LDAP esup.ldap.auth=false esup.ldap.url=ldap://ldap1.univ.fr:389/dc=univ,dc=fr ldap://ldap2.univ.fr:389/dc=univ,dc=fr esup.ldap.ssl=false esup.ldap.binddn= esup.ldap.bindpasswd= esup.ldap.persondirs.use=false esup.ldap.groups.use=false esup.ldap.groups.etu.formation=etud-formation #CAS esup.cas.auth=false esup.cas.proxy=false esup.cas.host=auth.univ.fr esup.cas.port.https= esup.cas.uri=/cas esup.cas.finalurl=https://${esup.cas.host}${esup.cas.port.https}${esup.cas.uri} esup.cas.uri.login=/login esup.cas.uri.validate=/servicevalidate esup.cas.uri.proxy=/proxy esup.cas.uri.logout=/logout esup.public.uri.login=/login esup.real.uri.callbackcas=/casproxyservlet #DB esup.db.auth=true esup.db.persondirs.use=true esup.db.username=sa esup.db.password= esup.db.url=jdbc:hsqldb:hsql://localhost:8887 esup.db.jdbcdriverjar=hsqldb.jar esup.db.classname=org.hsqldb.jdbcdriver esup.db.db-version=1.7.2 #MISC Document generated by Confluence on Jun 10, 2008 08:53 Page 10
esup.title.main=${esup.host.logicalname} - esup-dev ${uportal.ver} esup.host.logicalname=esup1 esup.session.lifetime=30 esup.languages=fr_fr,en_us esup.upload-maxsize=300000 esup.ws.groups=false esup.session.lifetime=30 esup.languages=fr_fr,en_us esup.pubchan=true esup.monitor=false esup.userprefs.save=false esup.log.file=${esup.root} /logs/portal.log\\ esup.log.size=50000kb\\ esup.log.level=info esup.stats.file=$ {esup.root}/logs/stats.log esup.stats.attributetype=edupersonprimaryaffiliation esup.stats.size=20000kb esup.keystore=${esup.root} /esup-portail.keystore Avec : Variable Description Exemple Version de package tomcat.update.conf Doit on mettre à jour le tomcat.update.conf=true DEV server.xml de Tomcat tomcat.update.conf=false tomcat.update.lib Doit on copier des librairies uportal dans tomcat.update.lib=true tomcat.update.lib=false DEV Tomcat tomcat.reloadable Active le contexte uportal tomcat.reloadable=true DEV comme rechargeable dans tomcat.reloadable=false Tomcat tomcat.port.shutdown Port Tomcat pour l'arrêt tomcat.port.shutdown=8005 DEV tomcat.port.http Port Tomcat pour le tomcat.port.http=8080 DEV connecteur HTTP tomcat.port.jk Port Tomcat pour la communication JK tomcat.port.jk=8009 DEV Document generated by Confluence on Jun 10, 2008 08:53 Page 11
esup.public.host Hostname connu à l'extérieur esup.public.host=ent.univ.fr DEV esup.public.proto Protocole d'accès connu à esup.public.proto=http DEV l'extérieur esup.public.port Port d'accès (vide = 80) esup.public.port= esup.public.port=8080 DEV esup.public.uri URI d'accès au portail (vide = /) esup.public.uri=/uportal esup.public.uri= DEV esup.public.finalurl URL complète d'accès au portail esup.public.finalurl= ${esup.public.proto}:// DEV ${esup.public.host}${esup.public.port}${esup.public.uri} esup.real.host Hostname réel (hors load esup.real.host= DEV balancer par exemple) ${esup.public.host} esup.real.host=entx.univ.fr esup.real.uri URI réel d'accès au portail esup.real.uri= DEV (hors JK par exemple) ${esup.public.uri} esup.real.port.https Port d'accès https (vide = esup.real.port.https= DEV 443) esup.real.port.https=8443 esup.real.https.finalurl URL complète d'accès esup.real.https.finalurl=https:// DEV (hors LB et JK) $ \{esup.real.host}${esup.real.port.https}${esup.real.uri} esup.ldap.auth Utilisation de LDAP pour l'authentification esup.ldap.auth=false esup.ldap.auth=true DEV esup.ldap.url URL d'accès LDAP esup.ldap.url=ldap:// ldap1.univ.fr:389/ DEV dc=univ,dc=fr esup.ldap.url=ldap:// ldap1.univ.fr:389/ dc=univ,dc=fr ldap:// ldap2.univ.fr:389/ dc=univ,dc=fr esup.ldap.ssl Active le LDAPS esup.ldap.ssl=false DEV esup.ldap.binddn DN de l'utilisateur pour esup.ldap.binddn= DEV faire la connexion LDAP esup.ldap.binddn=cn=reader,ou=system,dc=univ,dc=fr (vide = anonyme) esup.ldap.bindpasswd Mot de passe pour faire le esup.ldap.bindpasswd= DEV bind LDAP esup.ldap.bindpasswd=xxxxx esup.ldap.persondirs.use Utilisation de LDAP pour collecter des attributs esup.ldap.persondirs.use=false DEV utilisateur esup.ldap.groups.use Utilisation de LDAP pour les groupes (PAGS) esup.ldap.groups.use=falsedev esup.ldap.groups.use=true esup.ldap.groups.etu.formation Attribut LDAP esup.ldap.groups.etu.formation=etudformation DEV représentant la formation d'un etudiant (pour construire des groupes) Document generated by Confluence on Jun 10, 2008 08:53 Page 12
esup.cas.auth Utilisation de CAS pour l'authentification esup.cas.auth=false esup.cas.auth=true DEV esup.cas.proxy Utilisation du mode proxy esup.cas.proxy=false DEV CAS dans le portail esup.cas.proxy=true esup.cas.host Hostname du serveur CAS esup.cas.host=auth.univ.frdev esup.cas.port.https Numéro du port HTTPS du esup.cas.port.https= DEV serveur CAS (vide = 443) esup.cas.port.https=8443 esup.cas.uri URI de base du serveur CAS (vide=/) esup.cas.uri=/cas esup.cas.uri= DEV esup.cas.finalurl URL complète d'accès au esup.cas.finalurl=https:// DEV serveur CAS $ \{esup.cas.host}${esup.cas.port.https}${esup.cas.uri} esup.cas.uri.login URI pour le login CAS esup.cas.uri.login=/login DEV esup.cas.uri.validate URI pour valider un ticket esup.cas.uri.validate=/ DEV CAS servicevalidate esup.cas.uri.proxy URI pour être proxy esup.cas.uri.proxy=/proxydev esup.cas.uri.logout URI de logout CAS esup.cas.uri.logout=/ logout DEV esup.public.uri.login URI de login du portail esup.public.uri.login=/ Login DEV esup.real.uri.callbackcas URI du portail pour être esup.real.uri.callbackcas=/ DEV proxy CAS CasProxyServlet esup.db.auth esup.db.persondirs.use esup.db.username esup.db.password esup.db.url esup.db.jdbcdriverjar esup.db.classname esup.db.db-version esup.db.poolpreparedstatements Utilsation de la base de données uportal pour l'authentification Utilisation de la base de données uportal pour collecter des attributs utilisateurs Utilisateur se connectant a la base uportal Mot de passe pour se connecter à la base uportal URL de connexion à la base uportal Jar contenant le driver de connecion à la base uportal Nom de la classe gérant la connexion à la base uportal Version du serveur de base de donnée Préparation des connexions avant exécution (performance) esup.db.auth=true DEV esup.db.persondirs.use=true DEV esup.db.username=sa DEV esup.db.username=uportal esup.db.password= DEV esup.db.password=xxxxx esup.db.url=jdbc:hsqldb:hsql:// DEV localhost:8887 esup.db.url=jdbc:mysql:// mysql.univ.fr/uportal esup.db.jdbcdriverjar=hsqldb.jar DEV esup.db.jdbcdriverjar=mysql- connector-java-5.0.7- bin.jar esup.db.classname=org.hsqldb.jdbcdriver DEV esup.db.classname=com.mysql.jdbc.driver esup.db.db-version=1.7.2 esup.db.dbversion=4.0.18-max-log DEV esup.db.poolpreparedstatements=true DEV Document generated by Confluence on Jun 10, 2008 08:53 Page 13
esup.title.main esup.host.logicalname Titre affiché dans la balise esup.title.main= title des pages HTML ${esup.host.logicalname} Nom logique de l'ent (utilisé dans les logs par exemple) Temps d'expiration de la session DEV - esup-dev ${uportal.ver} esup.host.logicalname=esup1 DEV esup.session.lifetime esup.session.lifetime=30 DEV esup.languages Langue disponible esup.languages=fr_fr,en_us DEV esup.upload-maxsize Taille maximum des esup.uploadmaxsize=300000 DEV fichiers téléchargés dans le portail esup.ws.groups esup.pubchan esup.monitor esup.userprefs.save Exportation des groupes dans un Web Service sur le portail Publication des canaux par défaut lors d'un db.init Exportation d'informations (via un servlet) sur la mémoire, le nomb re d'utilisateurs, etc. Sauvegarde automatique des préférences de l'utilisateur à la déconnexion. esup.ws.groups=false esup.ws.groups=true esup.pubchan=true esup.pubchan=false esup.monitor=false esup.monitor=true DEV DEV DEV esup.userprefs.save=false DEV esup.userprefs.save=true esup.log.dir Dossier de stockage des logs esup.log.dir= ${esup.root}/logs esup.log.dir=/var/logs/ esup esup.log.file Fichier de logs du portail esup.log.file= DEV ${esup.log.dir}/portal.log esup.log.size Taille de rotation des logs esup.log.size=50000kb DEV esup.log.level Niveau de logs esup.log.level=info esup.log.level=debug esup.log.level=error esup.log.level=warn DEV esup.stats.file esup.stats.attributetype esup.stats.size Fichier de logs statistiquesesup.stats.file= ${esup.log.dir}/stats.log esup.stats.file=/home/ esup/stats/stats.log Attribut uportal contenant le type de personne Taille de rotation des logs de stats DEV esup.stats.attributetype=edupersonprimaryaffiliation DEV esup.stats.size=20000kb DEV esup.keystore Keystore java a utiliser pour les dialogue du portail en https esup.keystore= ${esup.root}/esupportail.keystore DEV Document generated by Confluence on Jun 10, 2008 08:53 Page 14
03 - custom.properties This page last changed on May 29, 2008 by jmarchal. Fichier custom.properties Ce fichier va vous permettre de d'écraser des propriétés contenu soit dans le buil.properties soit dans le config.properties. Par exemple le build.properties d'origine : java_home=/usr/java/jdk1.5 # CURRENT FOLDER esup.root=${basedir.conv} devel.mode=false esup.base=${esup.root}/portail esup.sources=${esup.base}/uportal_rel-${uportal.ver} esup.deploy=${esup.base}/webapps esup.build=${esup.sources}/build server.home=${esup.base}/tomcat-${tomcat.ver} server.temp=${server.home}/temp esup.custom=${esup.root}/custom esup.update=${esup.root}/update esup.resources=${esup.root}/resources esup.packages=${esup.root}/packages esup.tmp=${esup.root}/tmp config.file=${esup.root}/config.properties Et le custom.properties : java_home=/usr/java/jdk1.5 esup.sources=/home/uportal/up-26/src/uportal_rel-${uportal.ver} esup.deploy=/home/uportal/up-26/webapps-2.0.1-alpha server.home=/home/uportal/up-26/tomcat server.temp=/home/uportal/up-26/temp esup.custom=/home/uportal/up-26/custom [...] Dans ce cas c'est le custom.properties qui prime donc "esup.sources=/home/uportal/src/uportal_rel-$ Unknown macro: {uportal.ver} ". Il en est de même pour le config.properties. L'avantage de ce ficheir et que vous avez VOS propriété dans un seul fichier et en plus vous pouvez facilement retrouver les valeurs par défaut du package. Document generated by Confluence on Jun 10, 2008 08:53 Page 15
05 - Installation This page last changed on Jun 06, 2008 by vrepain. Installation du package Esup Ce paragraphe décrit de manière rapide le processus d'installation et de paramétrage ; les paragraphes suivants détaillent les différents paramètres ou options. Les répertoires d'installation sont paramétrables dans le fichier build.properties. Ces paramètres sont indiqués entre accolades.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 dans les différents répertoires utilisés. Deux modes d'installation sont possibles : Développement : pour faire une installation rapide, des tests, découvrir le produit. Ce mode permet d'installer également des applications tierces nécessaires au fonctionnement du portail : Tomcat, Ant, et un moteur de base HSQL. L'installation rapide minimale est décrite en bas de chapitre. Production. Ce mode installe uportal et l'adaptation Esup. Les applications tierces sont considérées déjà installées et configurées (voir prérequis). Prérequis Système d'exploitation Unix, Linux. L'installation en mode de développement peut être faite sur un système Windows. Base de données Fonctionne avec un SGBD acceptant du SQL standard et les transactions, et proposant un drivers JDBC natif. Testé avec MySQL (version 4 ou supérieure), PostgreSQL, Oracle. Les pilotes pour MySQL et PostgreSQL sont fournis dans le package. Si vous utilisez un autre système, placez le pilote dans le répertoire ${esup.custom}/uportal/lib/ container-common avant l'initialisation du portail (voir plus bas) Environnement JAVA Un JDK 1.5 doit être préalablement installé sur le (ou les) serveur supportant le portail. La variable JAVA_HOME doit être valuée, et le chemin $JAVA_HOME/bin rajouté au PATH ANT Le logiciel ANT doit être installé, avec une version égale ou supérieure à 1.6.5. La variable ANT_HOME doit être valuée, et le chemin $ANT_HOME/bin rajouté au PATH Authentification En environnement de production, un serveur CAS doit être opérationnel au sein de l'établissement. Annuaire LDAP L'établissement doit disposer d'un annuaire LDAP exhaustif et compatible Supann. Première installation Décompression de l'archive tar -xvzf esup-2.6-esup-2.x.y Document generated by Confluence on Jun 10, 2008 08:53 Page 16
Un répertoire esup-2.6-esup-2.x.y est créé. On appellera ce répertoire la 'racine' du package. Il correspond au paramètre ${esup.root} du fichier build.properties. Personnalisation du déploiement du portail Vous pouvez adapter le fichier build.properties pour personnaliser l'emplacement du kit de développement Java, le mode d'installation (développement ou production), les différents répertoires d'installation, l'emplacement du fichier de configuration du portail. Il faut au minimum préciser l'emplacement du kit de développement Java (${java_home}). Le paramètre ${devel_mode} permet d'indiquer si l'on veut faire une installation en mode de développement (DEV) ou de production (). Ceci a un impact sur les packages déployés et les tâches Ant disponibles. Récupération des archives des applications tierces ant getcomponents Télécharge les archives des applications uportal ( et DEV), Tomcat, Ant, HSQL (DEV uniquement) dans le répertoire ${esup.packages}. Décompression des archives des applications tierces ant unzip Les archives sont décompactées sous le répertoire ${esup.base}. Configuration du portail Vous devez adapter le fichier config.properties. C'est le principal travail à effectuer. Initialisation du portail ant init Cette tâche : Copie les scripts du répertoire ${esup.resources} /scripts vers la racine, copie les pilotes de base de données de ${esup.resources}/drivers vers ${esup.sources}/lib/ container-common, copie les fichiers de personnalisation Esup dans ${esup.update}/uportal vers le répertoire de distribution uportal (${esup.sources}), copie vos fichiers de personnalisation dans ${esup.custom}/uportal vers le répertoire de distribution uportal (${esup.sources}), adapte les fichiers de configuration d'uportal en fonction des paramètres de config.properties, adapte les fichiers de configuration de Tomcat en fonction des paramètres de config.properties (DEV uniquement) Test de la connection à la base de données du portail ant db.test Permet de valider les informations de connection à la base de données du portail, indiquées dans le fichier config.properties (paramètres ${esup.db.xxx}) : url d'accès à la base, nom et mot de passe de l'utilisateur, classe java utilisée. S'il s'agit d'une installation sur une nouvelle base de données, la base doit préalablement être créée et l'utilisateur indiqué dans le fichier config.properties doit avoir des droits suffisants sur les objets. Document generated by Confluence on Jun 10, 2008 08:53 Page 17
Cette tâche affiche diverses informations sur la base de données. Si elle s'exécute avec succès (affichage de "BUILD SUCCESSFUL"), vous pouvez passer à la suite. Sinon, vérifiez et corrigez les paramètres de la base. Si le sgbd est MySQL ou PostgreSQL, noter le "Database version" (dans les première lignes du rapport), et mettez cette valeur complète dans la propriété ${esup.db.db-version} du fichier config.properties. Initialisation de la base de données du portail ant db.init Cette tâche : Supprime les tables du portail indiquées dans le fichier ${esup.sources}/properties/db/esuptables.xml Insère les données indiquées dans le fichier ${esup.sources}/properties/db/esup-data.xml Créé dans la base les groupes définis dans le fichier ${esup.sources}/properties/groups/ esupgroupload.xml Publie tous les canaux définis dans le répertoire ${esup.sources}/properties/chanpub (correspond à la tâche ant chan.pub -Dchan.pub=all) Publie tous les layouts définis dans le répertoire ${esup.sources}/properties/layout (correspond à la tâche ant layout.import -Dusername=all) Déploiement du portail ant deploy Compile et copie les fichiers nécessaires vers l'environnement d'exécution du portail (${esup.deploy}) Démarrage du portail A partir de la racine du package :./start-esup.sh Vérifier dans le fichier journal de Tomcat que le moteur et les différents contextes sont bien démarrés. Vérifier dans le fichier journal du portail que uportal est bien démarré Modifications et redéploiements Si vous modifiez le fichier config.properties ou vos personnalisations dans ${esup.custom}/uportal, relancez les tâches ant init et ant deploy puis redémarrez le portail pour les prendre en compte Si vous modifiez des canaux ou des layouts, vous pouvez: Soit refaire un déploiement complet (ant init; ant db.init; ant deploy). Attention, ceci réinitialise la base donc à faire uniquement sur une base de tests. Soit refaire les publications : ant init puis ant chan.pub -Dchan.pub=all ou ant layout.import - Dusername=all Installation rapide en mode de développement Décompresser l'archive Vérifier que un JDK 1.5 minimum est installé et dans le chemin Modifier le paramètre java_home de build.properties ant getcomponents ant unzip ant init ant hsql.start (démarre la base HSQL embarquée avec la distribution) ant db.init ant deploy Document generated by Confluence on Jun 10, 2008 08:53 Page 18
./start_esup.sh ou start_esup.cmd selon le système d'exploitation Document generated by Confluence on Jun 10, 2008 08:53 Page 19
06 - Conseils d'utilisation This page last changed on Jun 05, 2008 by vrepain. Error formatting macro: toc: java.lang.nullpointerexception Les librairies uportal est packagé avec un certain nombre de librairies (fichiers.jar) nécessaires à son bon fonctionnement ; esup-portail ajoute un certain nombre de librairies communes à notre environnement. Certains canaux ont également besoin de librairies externes pour fonctionner ; les canaux 'natifs' uportal (hors les portlets) s'exécutent dans le contexte d'uportal ; ils partagent donc les mêmes librairies. Faite attention a ne pas avoir 2 fois la même librairie avec des noms différent (xalan-2.7.0.jar et xalan-2.7.2.jar par exemple) Les librairies portail sont maintenant découpées en dossier : clover : inutilisé pour l'instant compile : utilisé pour la compilation du portail et copié dans le webapps lors du deploiement) container-common : utilisé pour la compilation du portail et copié dans Tomcat/common/lib si (tomcat.update.lib=true) container-common-endorsed : utilisé pour la compilation du portail et copié dans Tomcat/common/ endorsed si (tomcat.update.lib=true) container-shared : utilisé pour la compilation du portail et copié dans Tomcat/shared/lib si (tomcat.update.lib=true) portlets : les portlets exemple du portail provided : utilisé pour la compilation du portail uniquement runtime : utilisé pour la compilation du portail et copié dans le webapps lors du deploiement) (utilisé aussi lors de la compilation des test) test : utilisé uniquement pour la compilation des tests Les canaux Au cours de la vie du portail, l'administrateur est amené à gérer son contenu : ajout / modification de canaux, modifications de fragments,... Il faut donc faire en sorte que ces actions soient les plus pérennes possibles, et qu'un retour en arrière soit possible simplement en cas de modification malheureuse. L'utilisation de lien symbolique semble la meilleur solution. Numérotation de version Les noms des packages Esup suivent la norme suivante : esup-a-esup-b.c.d[-rce] Avec : A : le numéro de version de uportal embarqué B : c'est une mise à jour majeure. Une procédure spécifique doit être mise en oeuvre. C : C'est une mise à jour 'intermédiaire'. Elle peut nécessiter une mise à jour de la base de données, de JVM,... Une procédure spécifique peut être nécessaire. D : C'est une mise à jour mineure ; ce document devrait suffire à couvrir les contraintes liées à ces mises à jour. Présence de RCE : Release Candidate, la version n'est pas encore stable a 100% mais proche de l'être. Document generated by Confluence on Jun 10, 2008 08:53 Page 20
Compte utilisateur "esup" Il est fortement conseillé d'installer un serveur apache en frontal d'esup-portail, via mod_jk (ou mod_proxy en apache 2.2). Il n'est donc pas nécessaire que le lancement d'esup-portail (en fait, le serveur J2EE supportant esupportail) se fasse sous le compte root, puisque le port TCP APJ13 peut être supérieur à 1024. Nous supposerons ici qu'un compte esup est créé. Toutes les actions nécessaires au fonctionnement d'esup-portail (à l'exception du frontal apache) seront faites sous le compte 'esup'. Tous les chemins file système paramétrés seront accessibles en écriture par ce compte. Exemple d'organisation FileSystem On va séparer l'environnement de paramétrage/compilation de l'environnement de production. Dans cet exemple, l'environnement de paramétrage/compilation sera /home/esup/src, l'environnement de production /home/esup/webapps. On suppose que le package à installer est esup-2.6-esup-2.x.y ; il est désarchivé dans /home/esup/src/ esup-2.6-esup-2.x.y. Voici un extrait du fichier esup.properties correspondant à l'exemple de ce document : java_home=/usr/java/jdk1.5 esup.sources=/home/esup/src/uportal_rel-${uportal.ver} esup.deploy=/home/esup/webapps server.home=/home/esup/tomcat server.temp=/home/esup/temp esup.custom=/home/esup/custom /ur/java/jdk1.5 est un lien symbolique vers la JVM 1.5 courante. /home/esup/src/esup-package est un lien symbolique vers le répertoire de décompactage du package, ici src/esup-2.6-esup-2.x.y. /home/esup/src/esup-sources est un lien vers le répertoire src/uportal_rel-2.6.1-ga (à créer avant ant esup.unzip). /home/esup/webapps est un lien symbolique vers webapps-x.y /home/esup/tomcat est un lien symbolique vers apache-tomcat-5.5.26 On crée également le répertoire /home/esup/canaux, qui sera la racine de désarchivage des différents canaux installés. Les personnalisations Les personnalisations propres à l'établissement se trouvent dans le répertoire /home/esup/custom, luimême subdivisé en sous-répertoires : Tomcat, uportal. Vous aurez au moins les choses suivantes dans le répertoire custom : custom/uportal/properties : On devrait y trouver au moins les fichiers suivants : persondirectory.xml : ce fichier permet de faire un 'mapping' entre des attributs LDAP (ou issus d'une base SQL) avec des attributs uportal. Voir ce document sur le wiki uportal. groups/pagsgroupstoreconfig.xml : définition des groupes dynamiques uportal. Voir ce document sur le wiki uportal. Document generated by Confluence on Jun 10, 2008 08:53 Page 21
chanpub/xxxxx.xml : les fichiers de publication des différents canaux. Même s'il est possible de déclarer / modifier dynamiquement dans uportal les canaux, nous préconisons de le faire par la publication de ces fichiers de description (utilisés par la commande ant uportal.pubchan), ceci afin de les rejouer ultérieur. dlm.xml : les modèles d'environnement utilisateurs poussés pour cette instance d'esup-portail. layouts/xxxx.xml : fichier cml réprésentant un modèle d'environnement utilisateur pour une population donnée custom/uportal/lib : comme indiqué dans un paragraphe suivant, ce répertoire contiendra les librairies (fichiers.jar) nécessaires à l'exécution de certains canaux. custom/uportal/webpages : contiendra les éventuels skins de l'établissement. Première installation du portail On utilise la procédure 'normale' : 1. ant -buildfile /home/esup/src/esup-package/build.xml getcomponents 2. ant -buildfile /home/esup/src/esup-package/build.xml unzip 3. ant -buildfile /home/esup/src/esup-package/build.xml init 4. ant -buildfile /home/esup/src/esup-package/build.xml db.test 5. ant -buildfile /home/esup/src/esup-package/build.xml db.init 6. ant -buildfile /home/esup/src/esup-package/build.xml deploy 7. /home/esup/src/esup-package/start-esup.sh Installation d'une nouvelle version du package Ce paragraphe décrit l'installation une version mineure, qui n'impacte pas la base esup-portail. Grâce aux différents liens symboliques utilisés, on s'assure d'un retour en arrière facile. On suppose ici qu'on installe la version esup-2.6-esup-2.0.2. Les liens symbolique On déporte les différents liens symboliques vers les nouveaux répertoires : /home/esup/src/esup-package vers src/esup-2.6-esup-2.0.2. /home/esup/src/esup-sources vers src/uportal_rel-2.6.2-ga /home/esup/webapps vers webapps-2.6-esup-2.0.2 Décompresser le package dans /home/esup/src donc vers src/esup-2.6-esup-2.0.2 Pour vos personnalisations D'une manière générale, commencer par lire le fichier CHANGELOG de la nouvelle version du package. Les modifications qui sont fortement susceptibles de nécessiter des modifications de paramètres sont préfixés de 5 étoiles "*****". Properties cp src/esup-2.6-esup-2.0.1/custom.properties src/esup-2.6-esup-2.0.2/ Installation Comme l'installation originale, sans l'installation de la base : 1. ant -buildfile /home/esup/src/esup-package/build.xml getcomponents 2. ant -buildfile /home/esup/src/esup-package/build.xml unzip 3. ant -buildfile /home/esup/src/esup-package/build.xml init 4. ant -buildfile /home/esup/src/esup-package/build.xml deploy Redéployer vos canaux. Document generated by Confluence on Jun 10, 2008 08:53 Page 22
Arrêt - Relance du portail D'une manière générale, il est préconisé de faire un redémarrage du portail à intervalles réguliers, toutes les nuits par exemple. Document generated by Confluence on Jun 10, 2008 08:53 Page 23
07 - Personnalisations This page last changed on Jun 06, 2008 by vrepain. Vos personnalisations (ou custom) Toute vos personnalisation DOIVENT être dans le dossier custom. Ce dossier se redécoupe en : 1. uportal 2. Tomcat Le dossier Tomcat n'est traité que dans le package esupdev. Pour les custom uportal, vous devez reproduire la structure du dossier source uportal. Par exemple si vous voulez faire des modifications perso dans le fichier Logger.properties vous devez le créer dans custom/uportal/properties/logger.properties. ATTENTION Avant de personnaliser un fichier vérifiez s'il n'est pas présent dans l'arborescence update. S'il est déjà présent dans ce dossier partez de celui-ci plutôt que de celui contenu dans les sources uportal car le fichier dans le dossier update contient des balises de remplacement utilisées par les configurations. Démarche Premier exemple : patcher le fichier [esup-sources]/properties/persondirectory.xml 1. mkdir custom/uportal/properties/ 2. Chercher dans l'update si ce fichier existe (find update -name 'persondirectory.xml') 3. Il existe, donc : cp update/uportal/properties/persondirectory.xml custom/uportal/properties 4. Adaptez votre fichier, par exemple on ajoute un mapping d'attribut LDAP (<entry key="mail"> <value>mail</value></entry>) 5. Vous allez trouver des TAG dans ce fichier car il est issu de l'update (@esup.ldap.groups.etu.formation@) ; il seront remplacés lors de l'appel à ant init. Vous pouvez les supprimer mais la configuration (en l'occurence esup.ldap.groups.etu.formation) n'aura plus d'effet sur cette partie. Second exemple : patcher le fichier [esup-sources]/webpages/error.jsp 1. mkdir custom/uportal/webpages/ 2. Cherchez dans l'update si ce fichier existe (find update -name 'error.jsp') 3. Il n'existe pas dans l'update, donc on va le recopier depuis les sources uportal : cp src/[esupsources]/webpages/error.jsp custom/uportal/webpages 4. Adaptez votre fichier, par exemple on ajoute un mapping d'attribut LDAP (<title>portal: Une erreur est survenu</title>) Lors de l'appel a ant init le fichier custom va etre recopié dans les source uportal. CONSEIL Je vous conseille de conserver une copie de sauvegarde des fichiers d'origines. cp src/[esup-sources]/webpages/error.jsp custom/uportal/webpages/error.jsp.orig cp custom/uportal/webpages/error.jsp.orig custom/uportal/webpages/error.jsp Personnalisation des groupes Pour définir les groupes dynamiques de votre établissement : Document generated by Confluence on Jun 10, 2008 08:53 Page 24
1. Adaptez le fichier custom/uportal/properties/groups/pagsgroupstoreconfig.xml (voir article détaillé : Gestion des groupes) 2. Redéployez : ant init; ant deploy; Personnalisation des canaux 1. Créez un fichier custom/uportal/properties/chanpub/<nom_canal>.xml par canal à publier (voir article détaillé : Publication de canaux) 2. Lancez ant init puis : soit ant chan.pub -Dchan.pub=all pour publier tous les canaux du répertoire chanpub, soit ant chan.pub -Dchan.pub=<nom_canal>.xml pour ne publier qu'un canal Personnalisation des environnements utilisateurs (layouts) L'environnement d'un utilisateur défini les onglets et menus qui lui sont affichés, ainsi que leur disposition (voir article détaillé : les DLM uportal) 1. Créez un fichier custom/uportal/properties/layouts/<nom_modele>.xml par modèle d'environnement utilisateur 2. Référencez et configurez ces modèles dans le fichier custom/uportal/properties/dlm.xml 3. Lancez ant init puis : soit ant layout.import -Dusername=all pour publier tous les modèles du répertoire layouts, soit ant layout.import -Dusername=<nom_modele> pour ne publier qu'un modèle La stratégie de création des environnements utilisateurs dépendra de la structure de l'établissement et de son ENT. On peut décider par exemple de créer un modèle par profil d'usager contenant l'ensemble des onglets et canaux, ou de créer un modèle par onglet, les profils d'usager étant déduits des droits d'accès définis dans dlm.xml et dans les canaux. Créer un thème Voir l'article détaillé : Personnalisations de look 1. Créez une structure custom/uportal/webpages/media/org/jasig/portal/layout/tab-column/xhtmltheme/<nom_theme> sur le modèle du dossier update/uportal/webpages/media/org/jasig/portal/ layout/tab-column/xhtml-theme/esup 2. Renommez les fichiers skin/esupxxx.css en skin/<nom_theme>xxx.css 3. Adaptez les feuilles de style dans skin 4. Remplacez dans le fichier skin/<nom_theme>.css les occurences esup par <nom_theme> 5. Modifiez les images et icônes dans les répertoires controls, institutional, navigation 6. Référencez le thème dans custom/uportal/webpages/media/org/jasig/portal/layout/tab-column/ xhtml-theme/skinlist.xml 7. Redéployez : ant init; ant deploy; Document generated by Confluence on Jun 10, 2008 08:53 Page 25