Pré-requis technologiques
Technologies employées au cours de ce support
Notez que différentes technologies et notions sont installées tout au long de ce support pour l'installation et la configuration de ORI-OAI. Même si la connaissance de ces technologies n'est pas requise, il est préférable de les maîtriser en partie pour une installation plus rapide et avancée de ORI-OAI :
- Tomcat
- Ant
- XML
- Spring
- Environnement Linux
- SVN
Environnement
Le projet ORI-OAI est entièrement développé dans un environnement J2EE. Aussi, le support qui vous est proposé ici se base entièrement sur un environnement Linux pour se rapprocher au mieux d'une mise en production. Les notions citées ci-après sont donc nécessaires :
- Connaître l'environnement Linux
- Avoir déjà installé une application J2EE (recommandé)
Pré-requis logiciels
Nous verrons dans ce document que certains composants extérieurs sont nécessaires au bon fonctionnement de ORI-OAI :
- jdk 1.6.0 (minimum révision 18)
- base de données SQL avec moteur transactionnel (MySQL + InnoDB, PostgreSQL, ..)
- les bases suivantes doivent être préalablement créées, avec un accès en lecture/écriture pour l'utilisateur défini dans le fichier common-parameters.properties (Remarque : le nom par défaut de ces bases peut être modifié dans ce même fichier) :
- une base pour la gestion des documents moissonnés : orioaiharvester par défaut
- une base pour la gestion des documents produits dans le workflow : orioaiworkflow par défaut
- une base pour la gestion du stockage des documents dans ESUP-ECM : esup-ecm_storage par défaut
- une base pour tous les autres besoins (indexation,recherche,gestion des relations,...) de la solution ESUP-ECM : esup-ecm par défaut
- les deux dernières uniquement si vous prévoyez l'utilisation d'ESUP-ECM !
- les bases suivantes doivent être préalablement créées, avec un accès en lecture/écriture pour l'utilisateur défini dans le fichier common-parameters.properties (Remarque : le nom par défaut de ces bases peut être modifié dans ce même fichier) :
- annuaire LDAP
- serveur SMTP
Nous définissons ici les différentes variables globales utilisées dans ce support :
[ORI_HOME] le dossier dans lequel vous ferez l'installation sur votre machine. (Note : lors des captures d'écran de ce support, le dossier ORI_HOME correspondait au dossier /usr/local/ori de notre machine)
[HOST_INSTALL] le nom de la machine sur laquelle vous faites l'installation
[JAVA_HOME] le dossier d'environnement du JDK de votre machine
[PATH_TOMCAT] le chemin vers le serveur tomcat dans le cas où vous utiliser un unique Tomcat pour tous les modules
[PROXY_HOST] l'URL de votre proxy au cas où la machine d'installation passe par un proxy
[PROXY_PORT] le port du proxy le cas échéant
[SMTP_ETABLISSEMENT] l'adresse du serveur SMTP de l'établissement (ex : smtp.insa-lyon.fr)
[SMTP_PORT_ETABLISSEMENT] le port du serveur SMTP de l'établissement (ex : 25)
[POP_ETABLISSEMENT] Le nom du serveur POP de l'établissement pour la réception de mails
[SMTP_ADMINISTRATOR_MAIL] l'adresse mail de l'administrateur afin de recevoir les mails durant les tests et lors de relevés de bugs
[SMTP_ADMINISTRATOR_NAME] le nom de l'administrateur afin de recevoir les mails durant les tests et lors de relevés de bugs
[ADMINISTRATOR_ID] Identifiant de l'administrateur de ORI-OAI dans le LDAP
[CAS_ETABLISSEMENT] l'adresse du serveur CAS de votre établissement si vous en utilisez un
[LDAP_ETABLISSEMENT] l'adresse de l'annuaire LDAP que vous utiliserez au cours de l'installation
[LDAP_BASE_DN] la base dn de l'annuaire LDAP que vous utilisez
[INDEXES_DATA_DIR] le dossier dans lequel seront écrits les indexes des différents modules
Vous devrez remplacer toutes les variables citées ci-dessus par leur valeur réelle chaque fois que celles-ci apparaissent dans le document.
Remarques générales
Les mots de passe
Dans ce tutoriel, nous utilisons des mots de passe simples. Lors d'un déploiement en production d'ORI-OAI, utilisez des mots de passe complexes et en phase avec la politique de mot de passe (si elle existe) mise en place dans votre établissement.
Versions du JDK et de Tomcat
La version 1.6 de ORI-OAI a été validée sous un JDK6.
L'installation des serveurs Tomcat peut être faite automatiquement lors des différentes procédures de déploiement. Dans le cas où vous souhaitez déployer sur un Tomcat existant, sachez que la version minimale requise est la 6.
Si toutefois vous souhaitiez déployer un ou plusieurs modules sur un Tomcat 5, vous devrez modifier le fichier build.xml des modules en question. En effet, la différence à notre niveau entre un Tomcat 6 et un Tomcat 5 est l'emplacement du dossier lib (Tomcat 6) ou common/lib (Tomcat 5). C'est ce chemin qu'il est nécessaire de modifier manuellement dans le fichier build.xml.
Remarques concernant la base de données SQL
Base de données transactionnelle
ori-oai-workflow comme ori-oai-harvester requièrent l'utilisation d'une base de données transactionnelle. On recommande l'usage de MySql avec le moteur Innodb.
Aussi, dans le cas de MySQL, il faut s'assurer que vous utilisez (par exemple mais on vous le recommande) le moteur InnoDB (le moteur MyISAM usuellement configuré par défaut n'étant pas transactionnelle, celui-ci ne convient pas).
Sous linux, dans my.cnf, pour les versions de mysql récentes, on pourra vérifier que l'on a :
default-storage_engine = innodb
Pour une version plus ancienne, l'option est de la forme :
default-table-type = innodb
Commandes pour vérifier en ligne de commande (client mysql) le storage utilisé sur une table de votre base :
mysql> use `ori-oai-workflow`; Database changed mysql> show table status like 'ORI_WORKFLOW_ACL_ROLE'; \+\+-\--\--\--\--\--\--\--\--\--\--\--{-}+\-+-\-\--\---\--\--\-\--\--\--{-}+\-\-+-\-\--\--\--\--{+}{+-}\--\--\--\--{-}+\-+-\--\--\--\--\---\--\--\--\--\--\--\--\--{-}+\-+-\--\-\--\--\--\---\--\--\--\--\--{-}{+}{+{-}+}{+}-\--\--\--\-\--\--\--\---\--\--\--\--\--\--{-}+\-+-\--\--\--\--\---\--\--\-\--\--\--{-}{+}{+{-}+}{+}-\--\--\--\-\--\--\--\---\--\--\--\--\--\--\--\--\--\--\--\---------------------------------------------------------\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--+\+\++{-}{-+}\| Name \| Type \| Row_format \| Rows \| Avg_row_length \| Data_length \| Max_data_length \| Index_length \| Data_free \| Auto_increment \| Create_time \| Update_time \| Check_time \| Create_options \| Comment \|+{-}{-+}\++{-}+\-+-\--\--\--\--\--\--\--\--\--\--{-}{-}{-}+\-+-\-\--\-\--\--\--\-\--\--\--{-}{-}{-}+\-\-+{-}+\-\-+-\--\-\--\--\--\--\--\--{-}{-}{-}+\-+{-}+\-+-\--\--\--\-\--\--\--\--\--\--\--\--\--{-}{-}{-}+\-+-\--\-\--\--\--\-\--\--\--\--\--\--{-}{-}{-}+\-+-\--\--\-\--\--\--\-\--\--\--\--\--\--\--{-}{-}{-}+\-+-\--\--\--\--\-\--\--\--\-\--\--\--{-}{-}{-}+\-+-\--\--\-\--\--\--\-\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\-----------------------------------------\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\--\| ORI_WORKFLOW_ACL_ROLE \| InnoDB \| Dynamic \| 5 \| 3276 \| 16384 \| NULL \| 16384 \| 0 \| 6 \| NULL \| NULL \| NULL \| \|-{-}{+}{+{-}+}{+}-\-\--\--{-}{+}{+{-}+}{+}-\--\--\--\--\- *{-}InnoDB{-}* -\--\--\--{-}+\-+{-}+\-+{-}-\--free: 3072 kB; (`oriAclObjectIdentityId`) REFER `ori-oai-workflow/ORI_WORKFLOW_ACL_OBJECT_IDENTITY`(`oriAclObjectIdentityId`) \|-+\-+{-}+\-+-\--\--\--\--\--\--\--\--\--{+}{+-}{-}-\--\-\--\-\--+\-+-\--\-\--\--\--{-}-\--\--\-\--+\-+-\-\--\--\--\--\--\--{-}{-}-\--\--\--+\-+{-}+\-+-\-\--\--\--\--\--\--\--\--\--{-}{-}-\--\--+\-\-+{-}+\-+-\--\-\--\--\--\--\--\--{-}{-}-\--\--\--+\-\-+-\--\--\-\--\--\--\--\--\--\-\--\--\--\--\-\+-\--\-\--\--\--\-\--\--\--{-}{-}-\-\+-\--\--\-\--\--\--\-\--\--\--\--\--\-----------------------------------------------------------------------------------------------------------------------------\+ 1 row in set (0.00 sec)
On notera enfin que PostgreSQL a l'avantage ici d'avoir un moteur transactionnel par défaut.
Encodage de la base de données
Le positionner en tant qu'option Tomcat est également préférable:
CATALINA_OPTS=-Dfile.encoding=UTF-8
Encodage et MySQL
Côté MySQL
Pour MySQL, le plus simple est de configurer l'UTF-8 à la fois au niveau des "Connection Character Sets" et des "Collations".
Pour ce faire, on ajoute dans la configuration de mysql (sous debian /etc/mysql/my.cnf) la confiuration suivante (après [mysqld] au même niveau que default-storage_engine = innodb :
character-set-server=utf8 collation-server=utf8_general_ci
On notera qu'après une telle modification il faut redémarrer le serveur mysql.
On peut ensuite vérifier la bonne prise en compte de ces variables :
mysql> SHOW VARIABLES LIKE 'character_set%'; +--------------------------+----------------------------+ | Variable_name | Value | +--------------------------+----------------------------+ | character_set_client | latin1 | | character_set_connection | latin1 | | character_set_database | utf8 | | character_set_filesystem | binary | | character_set_results | latin1 | | character_set_server | utf8 | | character_set_system | utf8 | | character_sets_dir | /usr/share/mysql/charsets/ | +--------------------------+----------------------------+ 8 rows in set (0.00 sec) mysql> SHOW VARIABLES LIKE 'collation%'; +----------------------+-------------------+ | Variable_name | Value | +----------------------+-------------------+ | collation_connection | latin1_swedish_ci | | collation_database | utf8_general_ci | | collation_server | utf8_general_ci | +----------------------+-------------------+ 3 rows in set (0.00 sec)
Côté client Hibernate
Si comme indiqué au dessus, on a positionné à la fois les collation et les character set à utf-8, cette configuration côté Hibernate n'est a priori pas nécessaire.
Ici on force Hibernate à demander un dialogue UTF-8 avec la base de données, cela en ajoutant dans les paramètres de connection
- useUnicode=true
- characterEncoding=utf8
- useOldUTF8Behavior=true
Pour ori-oai-workflow, dans conf/properties/spring/common/dao/dao.xml
On mettra à la place de
<property name="url"> <value>${hibernate.connection.url}?emulateLocators=true</value> </property>
cela :
<property name="url"> <value>${hibernate.connection.url}?emulateLocators=true&useUnicode=true&characterEncoding=utf8&useOldUTF8Behavior=true</value> </property>
Base de données pour ESUP-ECM / Nuxeo
Le projet ESUP-ECM utilisé pour le stockage des documents nécessite l'utilisation d'une base de données transactionnelle.
La base de données recommandée par Nuxeo (projet sur lequel s'appuie ESUP-ECM) est PostgreSQL. Cependant, une compatibilité avec MySQL a été établie dans le projet ESUP-ECM.
Il est extrêmement important de souligner les remarques spécifiques à chacun de ces 2 SGBD:
PostgreSQL
L'utilisation de PostgreSQL 8.3 nécessite la définition de certaines fonctions particulières. Avant de vous lancer dans l'installation, veuillez suivre la documentation suivante: http://doc.nuxeo.org/xwiki/bin/view/FAQ/UsingPostgreSQL83
MySQL
Lorsque vous passerez à l'étape d'installation, à aucun moment ne vous sera demandé de créer les tables de la base de données. En effet, toutes les tables sont créées automatiquement lors du premier démarrage de ESUP-ECM.
Si vous utilisez MySQL, il est nécessaire de procéder à une modification d'un type d'attribut de la base de données avant de faire le premier dépôt.
En effet, dans la version courante de ESUP-ECM, le champ nécessaire au stockage du plein texte a un format trop restrictifs pour les fichiers de taille moyenne.
Les modifications à faire portent donc sur l'attribut binarytext dans la table fulltext.
Il faut changer son type de text à longtext.
Dans le cas où vous ne faites pas cette modification avant, vous obtiendrez certainement l'erreur suivante lors du dépôt d'un fichier trop volumineux:
Exception: com.mysql.jdbc.MysqlDataTruncation. message: Data truncation: Data too long for column 'binarytext' at row 1