Doc : add export EPUB method
[ldapsaisie.git] / doc / install / install.docbook
1 <?xml version="1.0" encoding="UTF-8" ?>
2 <chapter>
3
4 <title>Installation</title>
5
6 <sect1>
7   <title>Pré-requis</title>
8   <itemizedlist>
9     <listitem><simpara>&php; 5 avec <parameter>magic_quotes_gpc</parameter> et <parameter>register_globals</parameter> à <literal>off</literal></simpara></listitem>
10     <listitem><simpara>Le support <application>LDAP</application> dans &php; (paquet <application>php5-ldap</application> dans <application>Debian</application>)</simpara></listitem>
11     <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>
12     <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>
13     <listitem><simpara>&netldap; (paquet <application>php-net-ldap2</application> dans <application>Debian</application> ou <command>pear install net_ldap2</command>)</simpara></listitem>
14     <listitem><simpara>&smarty; (paquet <application>smarty</application> dans <application>Debian</application>)</simpara></listitem>
15     <listitem><simpara>L'utisateur exécutant le serveur web doit avoir les droits d'écriture sur le dossier 'tmp'. En cas d'installation à partir du paquet Debian, ce dossier est remplacé par un lien symbolique vers le dossier <emphasis>/var/tmp/ldapsaisie/</emphasis>.</simpara></listitem>
16   </itemizedlist>
17   <warning><simpara>La librairie &netldap; oblige le fait que la racine DSE de
18   l'annuaire soit lisible en anonyme sinon la connexion à l'annuaire échouera
19   systématiquement.</simpara></warning>
20   <note><para>Cette documentation est écrite à l'aide du langage Docbook.
21   Les mécanismes d'exportation de celle-ci requiert un certain nombre de programmes
22   et librairies :
23   <itemizedlist>
24     <listitem><simpara><application>make</application> (paquet <application>make</application> dans <application>Debian</application>)</simpara></listitem>
25     <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>
26     <listitem><simpara><application>xmllint</application> (validation XML) (paquet <application>libxml2-utils</application> dans <application>Debian</application>)</simpara></listitem>
27     <listitem><simpara><application>jw</application> (exportation PDF) (paquet <application>docbook-utils</application> dans <application>Debian</application>)</simpara></listitem>
28     <listitem><simpara><application>dbtoepub</application> (exportation EPUB) (paquet <application>dbtoepub</application> dans <application>Debian</application>)</simpara></listitem>
29   </itemizedlist>
30   </para></note>
31 </sect1>
32
33 <sect1 id="install-download">
34   <title>Téléchargement</title>
35
36   <sect2 id="install-from-git">
37     <title>A partir du paquet Debian</title>
38     <para>L'installation à partir du paquet Debian peut être réalisée soit en
39     téléchargeant manuellement le paquet, soit en déclarant le dépôt APT suivant
40     dans votre fichier <emphasis>/etc/apt/sources.list</emphasis> :
41     <screen>
42       <command>deb http://ldapsaisie.easter-eggs.org/debian stable main</command>
43     </screen> 
44     Il ne vous restera ensuite plus qu'a installer le paquet <emphasis>ldapsaisie
45     </emphasis> avec la commande suivante :
46     <screen>
47       <command>apt-get install ldapsaisie</command>
48     </screen> 
49     Le fichier <emphasis>/etc/ldapsaisie/apache.conf</emphasis> est un example de
50     configuration du serveur web Apache. La configuration du logiciel ce fera ensuite
51     dans le dossier <emphasis>/etc/ldapsaisie/local/</emphasis>.
52     </para>
53   </sect2>
54   
55   <sect2>
56     <title>A partir de Git</title>
57     <para>Le dépôt Git peut être récupéré anonymement en utilisant la
58     commande suivante :
59     <screen>
60       <command>git clone git://git.labs.libre-entreprise.org/ldapsaisie.git</command>
61     </screen> 
62     La racine web de l'application se trouvera alors dans le dossier <emphasis>
63     /ldapsaisie/public_html/</emphasis>.
64     </para>
65   </sect2>
66
67   <sect2>
68     <title>A partir des snapshot</title>
69     <para>Toutes les nuits, un snapshot de l'arbre Git est réalisé et est
70     téléchargeable au format <emphasis>tar.gz</emphasis> à l'adresse suivante : 
71     <ulink url='http://ldapsaisie.easter-eggs.org/download/ldapsaisie-snapshoot.tar.gz'>
72     http://ldapsaisie.easter-eggs.org/download/ldapsaisie-snapshoot.tar.gz</ulink>
73     </para>
74   </sect2>
75   
76 </sect1>
77
78 &install-arbo;
79
80 <sect1>
81   <title>Tutoriel d'installation</title>
82   <para>Cette section décrit les différentes étapes de l'installation de
83   LdapSaisie. Deux méthodes d'installation sont présentées ici, l'une à
84   partir des sources du projet et l'autre à partir du paquet Debian.</para>
85   
86   <para>Dans ce tutoriel, nous partirons du principe que vous avez 
87   pleinement la main sur votre serveur (installation de nouveau paquet et
88   configuration de votre serveur web) et que l'installation à partir des sources
89   se fera dans le dossier <literal>/var/www/ldapsaisie</literal>. Nous partons
90   également du principe que votre annuaire LDAP est déjà en place. Nous
91   utiliserons pour cette exemple de mise ne oeuvre l'annuaire correspondant
92   au schéma et à la configuration présente dans les sources du projet dans
93   le dossier <literal>lsexample</literal>.</para>
94   
95 <orderedlist>
96   <listitem>
97   <para>La première étape consiste à installer le locigiel en tant que tel.
98   Pour une installation à partir du paquet Debian référez vous au chapitre
99   <link linkend="install-from-git">Téléchargement</link>. Une fois le paquet
100   Debian, la configuration du logiciel se fera dans le dossier
101   <emphasis>/etc/ldapsaisie/local/</emphasis>. Les fichiers placés dans ce
102   dossier prévaleront toujours aux fichiers fournis par le paquet Debian,
103   vous permettant facilement de modifier un composant existant ou dans écrire
104   de nouveaux. Ainsi, pour modifier un fichier CSS par exemple, il vous
105   suffira de le placer dans le dossier
106   <emphasis>/etc/ldapsaisie/local/css/</emphasis>.</para>
107
108   <para>Pour une installation à partir du code source, il vous faut
109   cloner le repos Git. Pour cela il vous faut avoir installés les outils de Git 
110   contenu, dans Debian, dans le paquet <literal>git-core</literal>. Le
111   dépôt Git doit ensuite être récupéré anonymement en utilisant la
112   commande suivante :
113   <screen>
114     <command>git clone git://git.labs.libre-entreprise.org/ldapsaisie.git</command>
115   </screen>
116   <note><simpara>Pour que cette commande se déroule correctement, vous devez avoir
117   accès au port TCP 9418 du serveur git.labs.libre-entreprise.org. En cas de problème
118   vérifiez votre firewalling.</simpara></note>
119   La suite des opérations se déroulera donc maintenant dans le dossier
120   <literal>/var/www/ldapsaisie</literal>. Pour avoir plus de détails sur
121   les élements qu'on retrouve dans ce dossier, vous pouvez consulter 
122   <link linkend="install-arbo">la section concernée</link>. Nous allons 
123   nous instérésser plus particulièrement :
124   <itemizedlist>
125     <listitem><simpara>au script <literal>upgradeFromGit.sh</literal>
126     permettant la mise à jour de votre repos tout en concervant les adaptations
127     que nous ferons pour l'usage d'LdapSaisie adapté à notre annuaire ;</simpara>
128     </listitem>
129     <listitem><simpara>au dossier <literal>config.local</literal> dans 
130     lequel seront stockés vos fichiers et vos adaptations de l'application ;
131     </simpara></listitem>
132     <listitem><simpara>au dossier <literal>public_html</literal> qui
133     correspond à la futur racine du site web de l'application.</simpara>
134     </listitem>
135   </itemizedlist>
136   Le principe de l'adaptation est ici de mettre vos fichiers personnalisés
137   dans le dossier <literal>config.local</literal>, de les déclarer dans
138   votre fichier <literal>config.local/local.sh</literal> contenant la liste
139   des fichiers devant être installés. Le fichier <literal>local.sh</literal>
140   est la source de configuration du script <literal>upgradeFromGit.sh</literal>.
141   Il faut donc dans un premier temps créer votre fichier
142   <literal>local.sh</literal> en copiant le fichier d'example
143   <literal>local.sh.example</literal>. Ce fichier est un script bash
144   déclarant les variables de configurations suivantes :
145   
146 <variablelist>
147   
148 <varlistentry>
149   <term>LOCAL_FILES</term>
150   <listitem>
151     <simpara>La liste des chemins des fichiers à installer dans l'arboressence
152     du site. Cette élément doivent être séparés par des espaces ou des
153     retour à la liste. Exemple :</simpara>
154 <programlisting>public_html/conf/config.inc.php
155 public_html/lang/fr_FR.UTF8/lang.php</programlisting>
156   </listitem>
157 </varlistentry>
158
159 <varlistentry>
160   <term>LOG_FILE</term>
161   <listitem>
162     <simpara>Nom du fichier de log des mises à jour.</simpara>
163   </listitem>
164 </varlistentry>
165
166 <varlistentry>
167   <term>THEME</term>
168   <listitem>
169     <simpara>Le nom du theme à installer (facultatif et non traité dans
170     ce tutoriel).</simpara>
171   </listitem>
172 </varlistentry>
173
174 <varlistentry>
175   <term>BUILD_DOC</term>
176   <listitem>
177     <simpara>Variable booléene définissant si la documentation doit être
178     compiler en utilisant le script <literal>buildDocExports.sh</literal>.
179     Ceci ne sera pas expliqué dans ce tutoriel et nous partirons donc du
180     principe que cette variable est à <literal>0</literal>.</simpara>
181   </listitem>
182 </varlistentry>
183
184 </variablelist>
185
186 <note><simpara>D'autres variables sont présentes dans ce fichier et
187 concerne uniquement la compilation de la documentation. Elle peuvent
188 être ignorée à partir du moment ou la variable
189 <literal>BUILD_DOC</literal> vaut <literal>0</literal>.</simpara></note>
190
191 <note><simpara>Il est possible d'utiliser dans ce fichier de configuration
192 la variable bash <literal>$ROOT_DIR</literal> correspondant au chemin
193 du dossier d'installation, c'est à dire dans notre exemple
194 <literal>/var/www/ldapsaisie</literal>.</simpara></note>
195   
196   </para>
197   </listitem>
198   
199   <listitem><simpara>La deuxième étape concerne la configuration globale
200   de l'application : Cette partie est principalement contenue dans le
201   fichier <emphasis>conf/config.inc.php</emphasis> (ou
202   <emphasis>/etc/ldapsaisie/local/conf/config.inc.php</emphasis> en cas
203   d'installation à partir du paquet Debian). En cas d'installation à partir
204   du code source, il faut donc dans un premier temps copier ce fichier dans
205   le dossier <literal>config.local</literal> et le déclarer dans la liste
206   des fichiers à déployer lors des mises à jour
207   (variable <literal>LOCAL_FILES</literal> dans le fichier 
208   <literal>local.sh</literal>). Il s'agit en particulier dans ce fichier
209   de configurer la connexion à votre annuaire. Vous pouvez vous inspirer
210   du fichier d'exemple fourni et pour plus de détails, reportez-vous à
211   <link linkend="config-globale">la section concernée</link>.
212   </simpara>
213   <note><simpara>Notez qu'il est possible de passer l'application en mode
214   <emphasis>debug</emphasis> ce qui peut être utile par la suite.</simpara></note>
215   </listitem>
216   
217   <listitem><simpara>La troisième étape concerne la configuration des
218   types de &LSobjects; : Chaque type d'objet manipulé par LdapSaisie doit
219   correspondre avec un type de LSobject.</simpara>
220     
221     <orderedlist>
222     
223     <listitem><para>Création du fichier de classe : Ce fichier contient la 
224     déclaration de la classe PHP correspondant au type de LSobject. Cette classe
225     étend la classe <emphasis>LSldapObject</emphasis> qui contient pour ainsi dire
226     toute les méthodes et proprités nécessaires pour les types de LSobject simples
227     (sans &LSrelation;). Les fichiers des classes sont contenus dans le dossier
228     <emphasis>/includes/class/</emphasis> et portent les noms composés de la 
229     manière suivante : 
230     <programlisting>class.LSobjects.[nom du type d'LSobject].php</programlisting>
231     Le plus simple pour cette étape est de copier un des fichiers d'exemple afin
232     de l'adapter en changeant le nom du type d'objet dans l'ensemble du fichier.
233     Pour cela, le fichier de classe du type <emphasis>LSpeople</emphasis> est le
234     plus simple car il ne contient que le strict minimum. Pour un fichier de classe
235     ayant des &LSrelations; à gérer, le fichier de classe <emphasis>LSgroup
236     </emphasis> contient déjà les méthodes nécéssaires pour gérer ces cas.
237     </para></listitem>
238     
239     <listitem><simpara>Configurer vos LSobject : Cette partie est certainement la
240     plus longue et consiste à déclarer l'ensemble des informations relatives aux
241     types des objets LDAP manipulés. Les fichiers d'exemples fournis vous seront
242     alors d'une aide précieuse. basé vous sur l'un de pour créer le votre. Pour
243     cela le fichier de configuration du type d'LSobjet <emphasis>LSpeople</emphasis>
244     est le plus complet et est un bon point de départ. Pour plus de détails sur les
245     élements de configuration de ce fichier, reportez-vous à 
246     <link linkend="config-LSobject">la section concernée</link>.</simpara>
247     </listitem>
248     
249     <listitem><simpara>Configurer si nécessaire les relations entre les objets
250     appelés &LSrelations;. Cette opération consiste dans un premier temps à écrire
251     les méthodes PHP nécessaires pour gérer ces relations : pour cela regardez le
252     fichier de classe du type <emphasis>LSgroup</emphasis>. Il faudra ensuite
253     déclarer ces relations dans la configuration des types d'LSobjects : Pour plus
254     de détails, reportez-vous à <link linkend="config-LSobject-LSrelation">la 
255     section concernée</link>.</simpara>
256     </listitem>
257     
258   </orderedlist>
259   
260   <important><simpara>En cas d'installation à partir du code source, pensez à déclarer
261   les fichiers que vous venez de créer dans la variable <literal>LOCAL_FILES</literal>
262   du fichier <literal>local.sh</literal>. Exemple pour le type d'LSobjet portant comme
263   nom <literal>LSexample</literal> :</simpara>
264 <programlisting>public_html/conf/LSobjects/config.LSobjects.LSexample.php
265 public_html/includes/class/class.LSobjects.LSexample.php</programlisting>
266   </important>
267   
268   <note><simpara>Vous pouvez également personnaliser l'interface : Il est
269   possible de personnaliser à votre goût l'interface en écrivant votre
270   template ou en modifiant simplement les fichiers CSS. Une partie de
271   cette documentation concernera bientôt cette problématique. Patience...
272   </simpara></note>
273   
274   </listitem>
275   
276   <listitem><simpara>En cas d'installation à partir du code source, une dernière
277   étape à ce niveau consiste à lancer le script <literal>upgradeFromGit.sh</literal>
278   pour qu'il installe les fichiers que vous venez de créer. Ce script est conçu pour
279   dire tout ce qu'il fait donc en cas de problème vous devriez rapidement comprendre
280   où cela coince. Dans tout les cas, n'hésitez pas à poser vos questions à la 
281   communauté sur la liste <email>ldapsaisie-users@lists.labs.libre-entreprise.org</email>.
282   </simpara></listitem>
283   
284 </orderedlist>
285
286
287
288 </sect1>
289  
290 </chapter>