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