ldapsaisie/doc/install/install.docbook

<?xml version="1.0" encoding="UTF-8" ?>
<chapter>

<title>Installation</title>

<sect1>
  <title>Pré-requis</title>
  <itemizedlist>
    <listitem><simpara>&php; 5 avec <parameter>magic_quotes_gpc</parameter> et <parameter>register_globals</parameter> à <literal>off</literal></simpara></listitem>
    <listitem><simpara>Le support <application>LDAP</application> dans &php; (paquet <application>php5-ldap</application> dans <application>Debian</application>)</simpara></listitem>
    <listitem><simpara>Le support <application>mhash</application> dans &php; (paquet <application>php5-mhash</application> dans <application>Debian Lenny</application>, intégré à <application>php5-common</application> dans <application>Debian Squeeze</application>)</simpara></listitem>
    <listitem><simpara>Le support <application>json</application> dans &php; (<command>pear install pecl/json</command> sur <application>RedHat</application>, intégré au paquet <literal>php5-common</literal> dans <application>Debian</application>)</simpara></listitem>
    <listitem><simpara>&netldap; (paquet <application>php-net-ldap2</application> dans <application>Debian</application> ou <command>pear install net_ldap2</command>)</simpara></listitem>
    <listitem><simpara>&smarty; (paquet <application>smarty</application> dans <application>Debian</application>)</simpara></listitem>
    <listitem><simpara>L'utisateur exécutant le serveur web doit avoir les droits d'écriture sur le dossier 'tmp'.</simpara></listitem>
  </itemizedlist>
  <warning><simpara>La librairie &netldap; oblige le fait que la racine DSE de
  l'annuaire soit lisible en anonyme sinon la connexion à l'annuaire échouera
  systématiquement.</simpara></warning>
  <note><para>Cette documentation est écrite à l'aide du langage Docbook.
  Les mécanismes d'exportation de celle-ci requiert un certain nombre de programmes
  et librairies :
  <itemizedlist>
    <listitem><simpara><application>make</application> (paquet <application>make</application> dans <application>Debian</application>)</simpara></listitem>
    <listitem><simpara>la feuille de style <literal>html</literal> XSL de Norman Walsh pour <application>Docbook</application> (fichier <literal>/usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl</literal> fournis par le paquet <application>docbook-xsl</application> dans <application>Debian</application>)</simpara></listitem>
    <listitem><simpara><application>xmllint</application> (validation XML) (paquet <application>libxml2-utils</application> dans <application>Debian</application>)</simpara></listitem>
    <listitem><simpara><application>jw</application> (exportation PDF) (paquet <application>docbook-utils</application> dans <application>Debian</application>)</simpara></listitem>
  </itemizedlist>
  </para></note>
</sect1>

<sect1 id="install-download">
  <title>Téléchargement</title>
  <para>Il n'existe pas encore de version stable publiée. Vous pouvez obtenir le
  code source soit en le rapatriant à partir du serveur Git, soit en téléchargeant
  le dernier snapshot nocturne de l'arbre Git.
  </para>
  
  <sect2>
    <title>A partir de Git</title>
    <para>Le dépôt Git peut être récupéré anonymement en utilisant la
    commande suivante :
    <screen>
      <command>git clone git://git.labs.libre-entreprise.org/ldapsaisie.git</command>
    </screen> 
    La racine web de l'application se trouvera alors dans le dossier <emphasis>
    /ldapsaisie/public_html/</emphasis>.
    </para>
  </sect2>

  <sect2>
    <title>A partir des snapshot</title>
    <para>Toutes les nuits, un snapshot de l'arbre Git est réalisé et est
    téléchargeable au format <emphasis>tar.gz</emphasis> à l'adresse suivante : 
    <ulink url='http://ldapsaisie.easter-eggs.org/download/ldapsaisie-snapshoot.tar.gz'>
    http://ldapsaisie.easter-eggs.org/download/ldapsaisie-snapshoot.tar.gz</ulink>
    </para>
  </sect2>
  
</sect1>

&install-arbo;

<sect1>
  <title>Tutoriel d'installation</title>
  <para>Cette section décrit les différentes étapes de l'installation de
  LdapSaisie. Aucune version d'LdapSaisie n'étant pour le moment sortie,
  cette méthode d'installation se base sur la récupération des sources
  directement dans le repos Git du projet. Des scripts ont été développés
  pour faciliter ces opérations de mises à jours tout en permettant une
  grande souplesse de confirguration et de personnalisation de l'application.</para>
  
  
  <para>Dans ce tutoriel, nous partirons du principe que vous avez 
  pleinement la main sur votre serveur (installation de nouveau paquet et
  configuration de votre serveur web) et que l'installation se fera 
  dans le dossier <literal>/var/www/ldapsaisie</literal>. Nous partons
  également du principe que votre annuaire LDAP est déjà en place. Nous
  utiliserons pour cette exemple de mise ne oeuvre l'annuaire correspondant
  au schéma et à la configuration présente dans les sources du projet dans
  le dossier <literal>lsexample</literal>.</para>
  
<orderedlist>
  <listitem>
  <para>La première étape consiste à faire un clonage du 
  repos Git. Pour cela il vous faut avoir installés les outils de Git 
  contenu, dans Debian, dans le paquet <literal>git-core</literal>. Le
  dépôt Git doit ensuite être récupéré anonymement en utilisant la
  commande suivante :
  <screen>
    <command>git clone git://git.labs.libre-entreprise.org/ldapsaisie.git</command>
  </screen>
  <note><simpara>Pour que cette commande se déroule correctement, vous devez avoir
  accès au port TCP 9418 du serveur git.labs.libre-entreprise.org. En cas de problème
  vérifiez votre firewalling.</simpara></note>
  La suite des opérations se déroulera donc maintenant dans le dossier
  <literal>/var/www/ldapsaisie</literal>. Pour avoir plus de détails sur
  les élements qu'on retrouve dans ce dossier, vous pouvez consulter 
  <link linkend="install-arbo">la section concernée</link>. Nous allons 
  nous instérésser plus particulièrement :
  <itemizedlist>
    <listitem><simpara>au script <literal>upgradeFromGit.sh</literal>
    permettant la mise à jour de votre repos tout en concervant les adaptations
    que nous ferons pour l'usage d'LdapSaisie adapté à notre annuaire ;</simpara>
    </listitem>
    <listitem><simpara>au dossier <literal>config.local</literal> dans 
    lequel seront stockés vos fichiers et vos adaptations de l'application ;
    </simpara></listitem>
    <listitem><simpara>au dossier <literal>public_html</literal> qui
    correspond à la futur racine du site web de l'application.</simpara>
    </listitem>
  </itemizedlist>
  Le principe de l'adaptation est ici de mettre vos fichiers personnalisés
  dans le dossier <literal>config.local</literal>, de les déclarer dans
  votre fichier <literal>config.local/local.sh</literal> contenant la liste
  des fichiers devant être installés. Le fichier <literal>local.sh</literal>
  est la source de configuration du script <literal>upgradeFromGit.sh</literal>.
  Il faut donc dans un premier temps créer votre fichier
  <literal>local.sh</literal> en copiant le fichier d'example
  <literal>local.sh.example</literal>. Ce fichier est un script bash
  déclarant les variables de configurations suivantes :
  
<variablelist>
  
<varlistentry>
  <term>LOCAL_FILES</term>
  <listitem>
    <simpara>La liste des chemins des fichiers à installer dans l'arboressence
    du site. Cette élément doivent être séparés par des espaces ou des
    retour à la liste. Exemple :</simpara>
<programlisting>public_html/conf/config.inc.php
public_html/lang/fr_FR.UTF8/lang.php</programlisting>
  </listitem>
</varlistentry>

<varlistentry>
  <term>LOG_FILE</term>
  <listitem>
    <simpara>Nom du fichier de log des mises à jour.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>THEME</term>
  <listitem>
    <simpara>Le nom du theme à installer (facultatif et non traité dans
    ce tutoriel).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>BUILD_DOC</term>
  <listitem>
    <simpara>Variable booléene définissant si la documentation doit être
    compiler en utilisant le script <literal>buildDocExports.sh</literal>.
    Ceci ne sera pas expliqué dans ce tutoriel et nous partirons donc du
    principe que cette variable est à <literal>0</literal>.</simpara>
  </listitem>
</varlistentry>

</variablelist>

<note><simpara>D'autres variables sont présentes dans ce fichier et
concerne uniquement la compilation de la documentation. Elle peuvent
être ignorée à partir du moment ou la variable
<literal>BUILD_DOC</literal> vaut <literal>0</literal>.</simpara></note>

<note><simpara>Il est possible d'utiliser dans ce fichier de configuration
la variable bash <literal>$ROOT_DIR</literal> correspondant au chemin
du dossier d'installation, c'est à dire dans notre exemple
<literal>/var/www/ldapsaisie</literal>.</simpara></note>
  
  </para>
  </listitem>
  
  <listitem><simpara>La deuxième étape concerne la configuration globale
  de l'application : Cette partie est principalement contenue dans le
  fichier <emphasis>conf/config.inc.php</emphasis>. Il faut donc dans un
  premier temps copier ce fichier dans le dossier <literal>config.local</literal>
  et le déclarer dans la liste des fichiers à déployer lors des mises à
  jour (variable <literal>LOCAL_FILES</literal> dans le fichier 
  <literal>local.sh</literal>). Il s'agit en particulier dans ce fichier
  de configurer la connexion à votre annuaire. Vous pouvez vous inspirer
  du fichier d'exemple fourni et pour plus de détails, reportez-vous à
  <link linkend="config-globale">la section concernée</link>.
  </simpara>
  <note><simpara>Notez qu'il est possible de passer l'application en mode
  <emphasis>debug</emphasis> ce qui peut être utile par la suite.</simpara></note>
  </listitem>
  
  <listitem><simpara>La troisième étape concerne la configuration des
  types de &LSobjects; : Chaque type d'objet manipulé par LdapSaisie doit
  correspondre avec un type de LSobject.</simpara>
    
    <orderedlist>
    
    <listitem><para>Création du fichier de classe : Ce fichier contient la 
    déclaration de la classe PHP correspondant au type de LSobject. Cette classe
    étend la classe <emphasis>LSldapObject</emphasis> qui contient pour ainsi dire
    toute les méthodes et proprités nécessaires pour les types de LSobject simples
    (sans &LSrelation;). Les fichiers des classes sont contenus dans le dossier
    <emphasis>/includes/class/</emphasis> et portent les noms composés de la 
    manière suivante : 
    <programlisting>class.LSobjects.[nom du type d'LSobject].php</programlisting>
    Le plus simple pour cette étape est de copier un des fichiers d'exemple dans
    le dossier <literal>config.local</literal> et de l'adapter en changeant
    le nom du type d'objet dans l'ensemble du fichier. Pour cela, le fichier
    de classe du type <emphasis>LSpeople</emphasis> est le plus simple
    car il ne contient que le strict minimum. Pour un fichier de classe
    ayant des &LSrelations; à gérer, le fichier de classe <emphasis>LSgroup
    </emphasis> contient déjà les méthodes nécéssaires pour gérer ces cas.
    </para></listitem>
    
    <listitem><simpara>Configurer vos LSobject : Cette partie est certainement la
    plus longue et consiste à déclarer l'ensemble des informations relatives aux
    types des objets LDAP manipulés. Les fichiers d'exemples fournis vous seront
    alors d'une aide précieuse. basé vous sur l'un de pour créer le votre. Pour
    cela le fichier de configuration du type d'LSobjet <emphasis>LSpeople</emphasis>
    est le plus complet et est un bon point de départ. Pour plus de détails sur les
    élements de configuration de ce fichier, reportez-vous à 
    <link linkend="config-LSobject">la section concernée</link>.</simpara>
    </listitem>
    
    <listitem><simpara>Configurer si nécessaire les relations entre les objets
    appelés &LSrelations;. Cette opération consiste dans un premier temps à écrire
    les méthodes PHP nécessaires pour gérer ces relations : pour cela regardez le
    fichier de classe du type <emphasis>LSgroup</emphasis>. Il faudra ensuite
    déclarer ces relations dans la configuration des types d'LSobjects : Pour plus
    de détails, reportez-vous à <link linkend="config-LSobject-LSrelation">la 
    section concernée</link>.</simpara>
    </listitem>
    
  </orderedlist>
  
  <important><simpara>Pensez à déclarer les fichiers que vous venez de créer dans la variable
  <literal>LOCAL_FILES</literal> du fichier <literal>local.sh</literal>. Exemple pour le
  type d'LSobjet portant comme nom <literal>LSexample</literal> :</simpara>
<programlisting>public_html/conf/LSobjects/config.LSobjects.LSexample.php
public_html/includes/class/class.LSobjects.LSexample.php</programlisting>
  </important>
  
  <note><simpara>Vous pouvez également personnaliser l'interface : Il est
  possible de personnaliser à votre goût l'interface en écrivant votre
  template ou en modifiant simplement les fichiers CSS. Une partie de
  cette documentation concernera bientôt cette problématique. Patience...
  </simpara></note>
  
  </listitem>
  
  <listitem><simpara>La dernière étape à ce niveau consiste à lancer le script
  <literal>upgradeFromGit.sh</literal> pour qu'il installe les fichiers
  que vous venez de créer. Ce script est conçu pour dire tout ce qu'il fait
  donc en cas de problème vous devriez rapidement comprendre où cela coince.
  Dans tout les cas, n'hésitez pas à poser vos questions à la communauté sur
  la liste <email>ldapsaisie-users@lists.labs.libre-entreprise.org</email>.
  </simpara></listitem>
  
  <listitem><simpara>Vous devriez dès à présent accèder à l'application
  via votre navigateur web à l'URL suivante :</simpara>
  <programlisting>http://[IP ou nom du serveur]/ldapsaisie/public_html</programlisting>
  </listitem>
  
</orderedlist>



</sect1>
 
</chapter>