Mise en place d'un système de publication de contenu basé sur le projet Apache Cocoon et le langage de balises DocBook Nowicki Christophe cscm@csquad.org Cocoon DocBook XML Java PDF OpenDocument RTF Text CMS Système de gestion de contenu Publication de contenu v0.1 2008-01-16 CN Première version publique. janvier 2007 Permission est accordée de copier, distribuer et/ou modifier ce document selon les termes de la Licence de Documentation Libre GNU (GNU Free Documentation License), version 1.1 ou toute version ultérieure publiée par la Free Software Foundation. Pas de section inaltérable. janvier 2007 Nowicki Christophe L'objectif de ce document est de décrire l'installation et la configuration d'un système de publication de contenu simplifié basé sur le langage de balises DocBook et le système de transformation de documents issu du projet Apache Coocon. La procédure d'installation est réalisée sur une distribution Debian GNU/Linux version « Etch » mais l'ensemble des instructions sont applicables à d'autres distributions GNU/Linux. Tous les documents disponibles à l'adresse (), sont écrit à l'aide du language DocBook, cette methode permet de séparer fond du document de sa mise en forme et anisi publier le document dans plusieurs formats (HTML, PDF, Texte, etc...). Cette possiblité forte interessante, est devenus au fils du temps un handicape. Car la moindre modification d'un document nécessite la régénération des differents formats d'export. J'ai donc cherché à simplifié et automatisé la procedure de publication. La résultat de ce travail est décrit dans ce document. DocBook est un langage de balisage conçu à l'origine pour la documentation technique informatique (matériel et logiciel). Il à été développé par l'éditeur O'Reilly pour les besoins de l'édition technique et plus particulièrement informatique. La grande force de ce langage est d'être un format XML totalement orienté sémantique, il n'inclut en effet aucune information de mise en forme ce qui permet d'utiliser ensuite la documentation ainsi structurée par tout type de support / lecteur. Un ensemble de feuilles de styles XSLT est disponible pour transformer des documents vers de nombreux formats tels que le HTML, XHTML, PDF, RTF, Texte, Microsoft WordML, OpenDocument, etc... Apache Cocoon est une plate-forme de développement d'applications web fondée sur la séparation des domaines techniques et l'assemblage de composants. Cocoon implémente ces concepts par la notion de "pipelines de composants", chaque composant du pipeline étant dédié à une fonction particulière. Cela permet d'utiliser une approche du type "Lego" pour la construction d'applications web, en assemblant des chaînes de composants, sans nécessiter de programmation. L'objectif de mon installation est de mettre en place un système de publication de contenu fonctionnant de la manière suivante : L'auteur édite un document à l'aide d'un éditeur XML (VIM, Emacs ou bien oXygen oXgen XML Editor http://www.oxygenxml.com/) en respectant le format Docbook. Une fois le document terminé, il l'envoi vers le serveur de publication de contenu à l'aide de Subversion. Lorsque'un utilisateur désire obtenir la version imprimable du document au format PDF, le clique sur un lien. A partir de celui-ci Cocoon, réalise la transformation du document XML à l'aide de la feuille de style XSLT et l'envoi à l'utilisateur. Les logiciels suivants sont nécessaires pour mettre en place le système : Nom Version Source Apache 2.0 Debian, paquet apache2 Tomcat 5.0 Debian, paquet tomcat5 Connecteur Apache pour Tomcat 2.0 Debian, paquet libapache2-mod-jk Subversion Debian, paquet subversion Support Subversion pour Apache Debian, paquet libapache2-mod-svn Feuilles de styles DocBook XSL de Norman Walsh 1.6.8 Debian, paquet docbook-xsl Source de Apache Cocoon 2.1.9 Disponible à l'adresse suivante : Kit de développement Java (JDK) de Sun 1.5 Debian, paquet sun-java5-jdk Vous pouvez installer l'ensemble des paquets Debian à l'aide des commandes apt : # apt-get install sun-java5-jdk apache2 \ tomcat5 libapache2-mod-jk \ libapache2-mod-svn docbook-xsl unzip subversion Regrouper les fichiers dans un répertoire commun : $ cd cocoon_files/ $ wget http://apache.fastorama.com/dist/cocoon/cocoon-latest-src.zip $ unzip cocoon-2.1.9-src.zip $ ls cocoon-2.1.10 cocoon-latest-src.zip Il faut compiler Cocoon pour obtenir une application Tomcat. Le système de compilation de Cocoon est modulaire, il faut donc préciser les composants à compiler à l'aide du fichier de configuration local.build.properties. $ cd cocoon-2.1.10/ $ cp build.properties local.build.properties $ vim local.build.properties Option Valeur exclude.deprecated true compiler.debug off Pour lancer la compilation de Cocoon, il suffit de taper la commande suivante : $ sh build.sh war ... Building jar: /home/cscm/cocoon_files/cocoon-2.1.10/build/cocoon/cocoon.war BUILD SUCCESSFUL Total time: 7 minutes 11 seconds Vous avez largement le temps de vous faire un bon café. On désactive le Java security manager, qui est activé par default mais qui empeche de déploiement de l'application. TOMCAT5_SECURITY=no Ce n'est pas la bonne méthode, mais c'est la plus rapide, car la description de la configuration du Security Manger dépasse le cadre de ce document, une fois votre installation finalisée, je vous invite vivement à lire la documentation disponible à cette addresse : The Apache Tomcat Security Manager HOWTO Il suffit de copier le fichier war dans le répertoire des webapps de Tomcat : # cp build/cocoon/cocoon.war /var/lib/tomcat5/webapps/ Pour vérifier le bon fonctionnement, il suffit de se connecter à l'adresse suivante : http://localhost:8080/cocoon Nous allons utilisé Subversion pour la gestion des fichiers sources. # mkdir /var/local/svn # svnadmin create /var/local/svn/cocoon # chown -R www-data: /var/local/svn/cocoon Il faut activer le module Subversion pour Apache # a2enmod dav_svn Enabling dav as a dependency This module is already enabled! Module dav_svn installed; run /etc/init.d/apache2 force-reload to enable. # /etc/init.d/apache2 force-reload Il faut ensuite créer un fichier de configuration pour votre site web dans le répertoire des sites disponibles dans apache2 : /etc/apache2/sites-available/svn <VirtualHost *:80> ServerName svn.csquad.org ErrorLog /var/log/apache2/svn.csquad.org/error.log CustomLog /var/log/apache2/svn.csquad.org/access.log common DocumentRoot /var/www <Location /> DAV svn SVNParentPath /var/local/svn/ </Location> </VirtualHost> Puis activer, cette configuration : # a2ensite svn Site svn installed; run /etc/init.d/apache2 reload to enable. # /etc/init.d/apache2 Vous pouvez tester le fonctionnement de votre depôt : $ svn co http://svn.csquad.org/cocoon Révision 0 extraite. Je vous propose d'utilisé l'organisation suivante pour votre dêpot : cocoon |-- branches |-- tags | `-- public | |-- article | `-- article.xml `-- trunk |-- article `-- article.xml Les documents qui se trouvent dans le répertoire tags/public, sont accessible publiquement et ceux du répertoire trunk sont les dernières versions et les documents en cours de rédaction. Cette organisation permet de simuler un simple système de pré-publication et de "versionner" l'ensemble de vos documents. Le module JK permet d'interfacer le serveur Web Apache avec le serveur d'application Tomcat. L'objectif est de rendre Cocoon accessible depuis votre site web à une adresse de type : http://votre_site_web/cocoon Pour cela, il faut : activer le module jk # a2enmod jk Module jk installed; run /etc/init.d/apache2 force-reload to enable. copier l'exemple de fichier de configuration fourni par le paquet dans le répertoire de configuration d'apache : # cp /usr/share/doc/libapache2-mod-jk/httpd_example_apache2.conf /etc/apache2/conf.d/jk.conf ajouter dans le fichier de configuration du module JK : /etc/apache2/conf.d/jk.conf JkMount /cocoon/* ajp13_worker relancer le serveur Apache # /etc/init.d/apache2 reload Vérifier le bon fonctionnement du module en vous connectant à l'adresse suivante :http://votre_site_web/cocoon Une fois l'ensemble installé, il faut configurer Cocoon de manière à transformer les fichiers qui se trouvent dans le dépôt Subversion en documents accessibles via le site Web dans différents formats. Pour cela nous allons modifier la section map:pipelines du fichier de configuration sitemap.xmap qui se trouve dans le répertoire : /var/lib/tomcat5/webapps/cocoon <map:pipeline> ... <!--+ | Subversion Content +--> <!-- Images --> <map:match pattern="**.png"> <map:read mime-type="image/png" src="http://svn.csquad.org/cocoon/{0}"/> </map:match> <map:match pattern="**.jpg"> <map:read mime-type="image/jpeg" src="http://svn.csquad.org/cocoon/{0}"/> </map:match> <!-- Acces direct au document au format XML --> <map:match pattern="**.xml"> <map:generate src="http://svn.csquad.org/cocoon/{0}"/> <map:serialize type="xml"/> </map:match> <!-- Transformation des documents XML en HTML a l'aide des feuilles de style de Norman Waslh--> <map:match pattern="**.html"> <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/> <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl"/> <map:serialize type="html"/> </map:match> <!-- Transformation des documents XML en xHTML a l'aide des feuilles de style de Norman Waslh--> <map:match pattern="**.xhtml"> <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/> <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/> <map:serialize type="xhtml"/> </map:match> <!-- Transformation des documents XML en PS a l'aide des feuilles de style de Norman Waslh et de FOP --> <map:match pattern="**.ps"> <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/> <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/> <map:serialize type="fo2ps"/> </map:match> <!-- Transformation des documents XML en PDF a l'aide des feuilles de style de Norman Waslh et de FOP --> <map:match pattern="**.pdf"> <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/> <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/> <map:serialize type="fo2pdf"/> </map:match> <!-- Transformation des documents XML en RTF a l'aide des feuilles de style de Norman Waslh et de FOP --> <map:match pattern="**.rtf"> <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/> <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/> <map:serialize type="fo2rtf"/> </map:match> ... <map:pipelines> Cette configuration permet de transformer le contenu de votre dêpot dynamiquement, et se base sur l'extension du fichier pour déterminer l'action à réaliser : Par exemple pour le document que vous êtes en train de lire, il n'existe qu'une seule version au format XML : http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.xml le document originale se trouve dans le dépôt Subversion : http://svn.csquad.org/cocoon/tags/public/cocoon/cocoon.xml Cette version est transformée dynamiquement dans plusieurs formats : http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.html http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.xhtml http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.pdf http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.ps http://www.csquad.org/cocoon/tags/public/cocoon/cocoon.rtf OpenDocument est un format ouvert de données pour les applications bureautiques : traitements de texte, tableurs, présentations, diagrammes, dessins et base de données bureautique. OpenDocument est la désignation d'usage d'un standard dont l'appellation officielle est OASIS Open Document Format for Office Applications, également abrégée par le sigle ODF. Un projet de feuille de style est en cours de réalisation (docbook2odf), celui-ci permet de transformet un fichier docbook au format OpenDocument. Puis l'installer, à l'aide des commandes suivantes : # cd /usr/src # svn co http://svn.comsultia.com/docbook2odf/trunk docbook2odf # cd docbook2odf # make install Depuis la version 2007 d'Office, Microsoft essaye d'introduire un nouveau format de fichier pour sa suite bureautique. Ce format à l'avantage d'être basé sur XML et d'être probablement documenté. Pour lire ce format avec les anciennes version de Micrsoft Office (XP, 2003, etc...), il faut installer le Microsoft Office Compatibility Pack. Il est possible de produire des documents au format WordML à l'aide des feuilles de style Docbook, pour cela il faut modifier la configuration de Cocoon et ajoutés les lignes suivantes dans votre fichier de configuration sitemap.xmap : <!-- Définition du serialiser --> <map:serializers> ... <map:serializer name="docx" mime-type="application/vnd.openxmlformats-officedocument.wordprocessingml.document" src="org.apache.cocoon.components.serializers.XMLSerializer"/> ... </map:serializers> <!-- Transformation des documents XML en WordML a l'aide des feuilles de style de Norman Waslh --> <map:match pattern="**.docx"> <map:generate src="http://svn.csquad.org/cocoon/{1}.xml"/> <map:transform src="/usr/share/xml/docbook/stylesheet/nwalsh/wordml/docbook.xsl"> <map:parameter name="wordml.template" value="/usr/share/xml/docbook/stylesheet/nwalsh/wordml/template.xml"/> </map:transform> <map:serialize type="docx"/> </map:match> Pour un document simple, cela fonctionne parfaitement, en revenche pour un document un peu plus complexe (tableaux, images, etc ...), le résultat final n'est pas garantie. Les feuilles de style XSLT de Norman Waslh, disposent de nombreuses options permettant de contrôler la mise en forme des documents : http://www.sagehill.net/docbookxsl/OptionsPart.html. Pour utiliser ces options, il est possible de procéder de plusieurs manières : De la manière suivante : <map:transform src="...xsl"> <map:parameter name='nom1' value='valuer1'/> <map:parameter name='nom2' value='valuer2'/> <map:parameter name='nom3' value='valuer3'/> ... </map:transform> En utilisant une autre feuille de style, comme d'écrit dans la documentation de docbook : Parameters in a file Au niveau de la sécurité du système, il faut protéger principalement l'accès au dépôt subversion. Pour cela, il suffit de protéger l'accès par mot de passe et de le limiter à votre réseau en modifiant le fichier de configuration du site Web : AuthType Basic AuthName "Subversion Repository" AuthUserFile /etc/apache2/svn.htpasswd # Authorise l'accès seulement au réseau local (pour la publication) # et à la machine locale (pour les transformations avec cocoon) Order deny,allow Deny from all Allow from 127.0.0.1 Allow from 192.168.0.0/24 # Demande l'authentification que pour les opérations d'écriture <LimitExcept GET PROPFIND OPTIONS REPORT> Require valid-user </LimitExcept> Puis créer le fichier de mot de passe pour vos utilisateurs : # htpasswd -c /etc/apache2/svn.htpasswd user New password: Re-type new password: Adding password for user user Ce système de publication de contenu n'est pas destiné à des sites à forte fréquentation, car les transformations XSLT et les feuilles de style utilisées sont très complexes. Elle nécessitent des ressources importantes au niveau du processeur et de la mémoire. Néanmoins, mon site fonctionne parfaitement sur une machine très modeste : VIA Mini ITX C3 600Mhz et 512Mo de mémoire. La plupart des optimisations doivent se faire un niveau de l'utilisation mémoire de Java et de la gestion du cache de Cocoon. Pour configurer la gestion de la mémoire, il faut éditer la variable CATALINA_OPTS du fichier /etc/default/tomcat5. Il faut choisir la bonne configuration en fonction de la quantité de mémoire disponible sur votre serveur. Pour vous aider, je vous invite à vous consulter le document suivant : Java Tuning White Paper Il y'a plusieurs options interessantes dans le fichier cocoon.xconf qui se trouve dans le répertoire /var/lib/tomcat5/webapps/cocoon/WEB-INF Option Valeur sitemap check-reload no La récupèration du fichier source XML à partir du dépôt est une opération récurrente, qu'il est possible d'optimiser à l'aide de la gestion du cache. Pour cela, il faut modifié la déclaration de la source est ajouté le préfix cached, comme ceux-ci : <map:generate src="cached:http://svn.csquad.org/cocoon/{1}.xml"/> Voici la sortie de logiciel Apache Benchmark : $ab -n 100 -c 5 http://www.csquad.org/cocoon/trunk/cocoon/cocoon.html This is ApacheBench, Version 2.0.40-dev <$Revision: 1.146 $> apache-2.0 Copyright 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/ Copyright 2006 The Apache Software Foundation, http://www.apache.org/ Benchmarking www.csquad.org (be patient).....done Server Software: Apache/2.2.3 Server Hostname: www.csquad.org Server Port: 80 Document Path: /cocoon/trunk/cocoon/cocoon.html Document Length: 47673 bytes Concurrency Level: 5 Time taken for tests: 5.586575 seconds Complete requests: 100 Failed requests: 0 Write errors: 0 Total transferred: 4806200 bytes HTML transferred: 4767300 bytes Requests per second: 17.90 [#/sec] (mean) Time per request: 279.329 [ms] (mean) Time per request: 55.866 [ms] (mean, across all concurrent requests) Transfer rate: 840.05 [Kbytes/sec] received Connection Times (ms) min mean[+/-sd] median max Connect: 0 0 0.2 0 1 Processing: 69 187 533.3 111 5426 Waiting: 45 155 534.6 79 5412 Total: 69 187 533.3 111 5426 Percentage of the requests served within a certain time (ms) 50% 111 66% 126 75% 145 80% 154 90% 216 95% 341 98% 426 99% 5426 100% 5426 (longest request) Comme on peux le voir, la 1ère requête, qui n'est pas mise en cache, est assez longue (5500 ms) et les autres requêtes sont bien plus rapides. Voici décrites rapidement quelques idées d'améliorations et d'évolutions du système Le système de gestion d'événements ("Hooks") de Subversion permet d'exécuter des actions sur le serveur lorsqu'une opération est réalisée sur le dépôt. Via ce système, il est possible de valider le contenu des fichiers XML par rapport à la DTD Docbook et de refuser automatiquement les fichiers qui ne sont pas formatés correctement. Docbook permet de décrire, l'historique des révisions d'un document à l'aide du tag revhistory. Ces informations sont directement disponibles dans le dêpot Subversion, il serait intérressant de les exploiter automatiquement.