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