1. Liens utiles

2. 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 :

2.1. 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.

2.2. 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.

2.3. 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.

La lecture du document d'installation du package esup-portail est un préalable à la bonne compréhension de ce document.

3. 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.

3.1. 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.

3.2. 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

On crée également le répertoire /home/esup/BUILD/canaux, qui sera la racine de désarchivage des différents canaux installés.

3.3. 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 :

3.3.1. Custom/uPortal/properties

On devrait y trouver au moins les fichiers suivants :

3.3.2. 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.

3.3.3. Custom/uPortal/webpages

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

3.4. Première installation du portail

On utilise la procédure 'normale' :

4. 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 fichier build.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 un ant esup.init puis ant 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.

5. 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.

5.1. Liens symboliques

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

5.2. désarchivage du package

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

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

5.3.1. 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.

5.3.2. 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).

5.4. Installation

Comme l'installation originale, sans l'installation de la base :

Puis, nouveau déploiement des canaux :

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

5.5. 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.

6. 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.

6.1. 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

6.2. 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 :

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