Liens utiles

• [Document d'installation
  du package esup-portail|InstallPackage2-5Esup.html]
• [Paramétrage
  du fichier personDirectory.xml|http://www.ja-sig.org/wiki/display/UPC/PersonDirectory]
• Paramétrage et utilisation des groupes
  • [Paramétrage
    du fichier compositeGroupServices.xml|../gestion_groupes/serviceGroup/composite.html]
  • [Service de
    groupe 'local'|../gestion_groupes/serviceGroup/local.html]
  • [Service de
    groupes 'LDAP"|../gestion_groupes/serviceGroup/ldap.html]
  • [Groupes
    PAGS|../gestion_groupes/serviceGroup/pags.html]
  • [Documentation
    groupes PAGS sur le wiki uportal|http://www.ja-sig.org/wiki/display/GAP/uPortal+PAGS+documentation]

Généralités

Ce document donne un exemple d'organisation d'une installation esup-portail qui permet de faciliter la maintenance, et en particulier la mise à jour de nouvelles versions en limitant les efforts et les risques.

Il ne prétend pas être une bible : chaque installation est à adapter en fonction de l'environnement cible : mono ou multi-serveurs, politique de site, ...

Les différentes problématiques à prendre en compte sont les suivantes :

Gestion des 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.

Gestion des canaux, des fragments

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.

Mises à jour du 'socle' esup-portail

C'est la mise à jour du package uPortal-w.z-esup.y (exemple : uPortal-2.5-esup-1). Suivant l'ampleur de la mise à jour, la procédure va différer.

w, z sont les indices de mise à jour d'uPortal, y un sous-indice esup-portail.

• w : c'est une mise à jour majeure. Une procédure spécifique doit être mise en oeuvre.
• z : 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.
• y : C'est une mise à jour mineure ; ce document devrait suffire à couvrir les contraintes liées à ces mises à jour.
  La lecture du [document
  d'installation du package esup-portail|InstallPackage2-5Esup.html] est un préalable à la bonne compréhension de ce document.

Exemple d'installation du 'socle'

Afin de faciliter la compréhension, nous allons prendre un exemple d'installation 'générique' ; cette installation ne correspond volontairement pas à un cas réel.

Elle est proposée en trame de la documentation. C'est bien un exemple qui est proposé, pas un modèle à appliquer systématiquement.

Création d'un compte lié au portail

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 esup-portail) 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 à ce compte.

Organisation file-système

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/BUILD, l'environnement de production /home/esup/PROD.

On suppose que le package à installer est uPortal-2.5-esup-1 ; il est désarchivé dans /home/esup/BUILD/.

Voici un extrait du fichier esup.properties correspondant à l'exemple de ce document :

java_home=/usr/java/jdk1.5
esup.custom=/home/esup/BUILD/Custom
esup.root=/home/esup/BUILD/uPortal-package
esup.distrib=/home/esup/BUILD/uPortal-sources
esup.custom=/home/esup/BUILD/Custom
esup.deploy=/home/esup/PROD/webapps
server.home=/home/esup/PROD/Tomcat
server.temp=/home/esup/PROD/temp

• /ur/java/jdk1.5 est un lien symbolique vers la JVM 1.5 courante.
• /home/esup/BUILD/uPortal-package est un lien symbolique vers le répertoire de décompactage du package, ici BUILD/uPortal-2.5-esup-1.

• /home/esup/BUILD/uPortal-sources est un lien vers le répertoire BUILD/uPortal-2.5-esup-1-sources (à créer avantant esup.unzip
  ).

• /home/esup/PROD/webapps est un lien symbolique vers PROD/webapps-2.5-esup-1
• /home/esup/PROD/Tomcat est un lien symbolique vers PROD/Tomcat_5-5-9
  On crée également le répertoire /home/esup/BUILD/canaux, qui sera la racine de désarchivage des différents canaux installés.

Personnalisations

Les personnalisations propres à l'établissement se trouvent dans le répertoire /home/esup/BUILD/Custom, lui-même subdivisé en sous-répertoires : ROOT, 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 :

• uPortal55.xml : C'est un fichier qui permet de définir les pools Tomcat de connexion aux différents bases de données.
• 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|http://www.ja-sig.org/wiki/display/UPC/PersonDirectory] sur le wiki uportal.
• groups/PAGSGroupStoreConfig.xml : définition des groupes dynamiques uPortal. Voir [ce
  document|http://www.ja-sig.org/wiki/display/GAP/uPortal+PAGS+documentation] sur le wiki uportal.

• 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 commandeant
  uportal.pubchan
  ), ceci afin de les rejouer ultérieur.

• al/xx-fragments.xml : les fragments poussés pour cette instance d'esup-portail.

  Custom/uPortal/lib

  
  Comme indiqué dans un pragraphe suivant, ce répertoire contiendra les librairies (fichiers .jar) nécessiare à l'exécution de certains canaux.

  Custom/uPortal/webpages

  
  Ca contenir les éventuels skins de l'établissement.

  Première installation du portail

  
  On utilise la procédure 'normale' :

• ant -buildfile
  /home/esup/BUILD/uPortal-package/build.xml
  esup.unzip

• ant -buildfile
  /home/esup/BUILD/uPortal-package/build.xml
  esup.init

• ant -buildfile
  /home/esup/BUILD/uPortal-package/build.xml
  esup.deploy

• ant -buildfile
  /home/esup/BUILD/uPortal-package/build.xml
  esup.db.init

Installation des canaux

Comme indiqué prédédemment, un répertoire dédié aux canaux a été créé.

Chaque canal à la norme esup contient à sa racine un fichierbuild.properties
, qui contient au moins les trois propriétés tomcat.home, uportal.home, deploy.home ; voici comment les valuer dans notre exemple :

#Repertoire d'installation de Tomcat
tomcat.home  = /home/esup/PROD/Tomcat

#Repertoire d'installation d'uPortal
uportal.home = /home/esup/BUILD/uPortal-sources

#Repertoire de deploiement
deploy.home  = /home/esup/PROD/webapps/uPortal

A la racine du répertoire /home/esup/BUILD/canaux, un script shell est créé, afin de pouvoir compiler/déployer facilement l'ensemble des canaux, et de pouvoir rejouer cette installation (le terme déploiement ici ne comprend pas la déclaration des canaux dans la base esup-portail, mais la compilation et la recopie des classes java et des fichiers annexes aux canaux dans l'environnement de production).

Voici ce script :

#!/bin/sh

UPORTAL_CHANNEL_DIR=/home/esup/BUILD/canaux

CHANNELS="esup-utils-mag-2.10-RC-3 connectors-1.06-RC-1 CAnnuaire-3.0-RC-4 CActu-1.0-Rc-2 .... "

for channel in $CHANNELS
do
  if [ -d  $UPORTAL_CHANNEL_DIR/$channel ]; then
      /home/uportal/ant.sh -buildfile $UPORTAL_CHANNEL_DIR/$channel/build.xml clean > /dev/null 2>&1   
      echo -n "Deploy $channel : "

      /home/uportal/ant.sh -buildfile $UPORTAL_CHANNEL_DIR/$channel/build.xml deploy | grep BUILD 
  else
     echo -n "###### $channel pas trouve #####"
  fi
done

Une attention particulière doit être apportée aux libraires (fichiers .jar) nécessaires à certains canaux. Ces librairies se trouvent habituellement dans le sous-répertoire lib de la racine de désarchivage du canal.

Ces librairies doivent être ajoutées en final dans le répertoire de librairies d'esup-portail : PROD/webapps/uPortal/WEB-INF/lib.

Il est déconseillé de les ajouter directement dans ce répertoire ; nous conseillons de les ajouter dans BUILD/Custom/uPortal/lib, puis de lancer ensuite unant esup.init
puisant
esup.deploy
.

Ceci permet de suivre plus facilement les librairies liées aux canaux. En particulier, avant de recopier une nouvelle librairie dans ce répertoire, il faut s'assurer qu'un autre librairie de même nom n'y est pas présente, afin d'éviter les conflits.

Installation d'une nouvelle version du package

Ce paragraphe décrit l'installation une version mineure, qui n'impacte pas la base esup-portail.

Grace 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 uPortal-2.5-esup-2.

Liens symboliques

On déporte les différents liens symboliques vers les nouveaux répertoires :

• /home/esup/BUILD/uPortal-package vers BUILD/uPortal-2.5-esup-2.
• /home/esup/BUILD/uPortal-sources vers BUILD/uPortal-2.5-esup-2-sources
• /home/esup/PROD/webapps vers PROD/webapps-2.5-esup-2

  désarchivage du package

  
  Dans /home/esup/BUILD, donc vers BUILD/uPortal-2.5-esup-2

  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 "*****".

esup.properties

 cp BUILD/uPortal-2.5-esup-1/esup.properties
BUILD/uPortal-2.5-esup-2/ 

Vérifier que les paramètres sont toujours corrects. Voir CHANGELOG. Si modification nécessaire, penser à sauvegarder l'ancien fichier.

Custom/uPortal

Vérifier que les fichiers que vous avez personnalisés n'ont pas été modifiés par cette nouvelle version. Si nécessaire, les adapter (sauvegarde préalable).

Installation

Comme l'installation originale, sans l'installation de la base : *ant -buildfile
/home/esup/BUILD/uPortal-package/build.xml
esup.init 

• ant -buildfile
  /home/esup/BUILD/uPortal-package/build.xml
  esup.deploy

Puis, nouveau déploiement des canaux :

 /home/esup/BUILD/canaux/deploy.sh

Si problème

Il est possible de revenir en arrière très rapidement, en remodifiant les 3 liens symboliques liés à la version du package esup-portail.

Cas du load-balancing

De nombreux sites utilisent un load-balancer pour répartir la charge des requêtes sur plusieurs serveurs esup-portail.

Nous exposons ici une méthode qui permet de maintenir les différents serveurs synchrones.

On suppose que l'adresse publique d'accès au portail est http://ent.univ.fr, et que 3 serveurs réels dont installés : ent1.univ.fr, ent2.univ.fr, ent3.univ.fr.

Paramétrage

Dans le fichier esup.properties, le paramètre esup.multiservers doir être valué à true.

Si vous désirez regrouper les logs (et/ou les stats) des différents instances de portail dans un seul fichier, il est facile de modifier le fichier de propriétés Logger.properties.

Voici un extrait permettant ceci :

syslog_host=syslog.univ.fr

log4j.appender.R=org.apache.log4j.net.SyslogAppender
log4j.appender.R.SyslogHost=${syslog_host}
log4j.appender.R.Facility=LOCAL5

Principe

Le principe est d'utiliser un serveur comme maître ; c'est sur ce serveur (ici, ent1) que l'on fera les différents paramétrages, compilations, déploiements, ...

Ensuite, il suffit de déployer l'environnement de production vers les serveurs 'esclaves'. En pratique, ceci peut se faire chaque nuit, depuis un script exécuté sur les esclaves, qui réalise les opérations suivantes :

• arrêt du portail

• rsync
  du répertoire /home/esup/PROD

• adaptation des quelques fichiers liés au serveur réel :
  • Logger.properties
  • portal.properties (logicalname)
  • web.xml (call back CAS)
  • ...

• relance du portail

  Arrêt - Relance du portail

  
  D'une manière générale, il est préconisé de faire un redémarrage du portail à intervalle régulier, toutes les nuits par exemple.