Doc : Added note about git acces and firewalling in the how-to.
[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   <note><simpara>Pour que cette commande se déroule correctement, vous devez avoir
84   accès au port TCP 9418 du serveur git.labs.libre-entreprise.org. En cas de problème
85   vérifiez votre firewalling.</simpara></note>
86   La suite des opérations se déroulera donc maintenant dans le dossier
87   <literal>/var/www/ldapsaisie</literal>. Pour avoir plus de détails sur
88   les élements qu'on retrouve dans ce dossier, vous pouvez consulter 
89   <link linkend="install-arbo">la section concernée</link>. Nous allons 
90   nous instérésser plus particulièrement :
91   <itemizedlist>
92     <listitem><simpara>au script <literal>upgradeFromGit.sh</literal>
93     permettant la mise à jour de votre repos tout en concervant les adaptations
94     que nous ferons pour l'usage d'LdapSaisie adapté à notre annuaire ;</simpara>
95     </listitem>
96     <listitem><simpara>au dossier <literal>config.local</literal> dans 
97     lequel seront stockés vos fichiers et vos adaptations de l'application ;
98     </simpara></listitem>
99     <listitem><simpara>au dossier <literal>public_html</literal> qui
100     correspond à la futur racine du site web de l'application.</simpara>
101     </listitem>
102   </itemizedlist>
103   Le principe de l'adaptation est ici de mettre vos fichiers personnalisés
104   dans le dossier <literal>config.local</literal>, de les déclarer dans
105   votre fichier <literal>config.local/local.sh</literal> contenant la liste
106   des fichiers devant être installés. Le fichier <literal>local.sh</literal>
107   est la source de configuration du script <literal>upgradeFromGit.sh</literal>.
108   Il faut donc dans un premier temps créer votre fichier
109   <literal>local.sh</literal> en copiant le fichier d'example
110   <literal>local.sh.example</literal>. Ce fichier est un script bash
111   déclarant les variables de configurations suivantes :
112   
113 <variablelist>
114   
115 <varlistentry>
116   <term>LOCAL_FILES</term>
117   <listitem>
118     <simpara>La liste des chemins des fichiers à installer dans l'arboressence
119     du site. Cette élément doivent être séparés par des espaces ou des
120     retour à la liste. Exemple :</simpara>
121 <programlisting>public_html/conf/config.inc.php
122 public_html/lang/fr_FR.UTF8/lang.php</programlisting>
123   </listitem>
124 </varlistentry>
125
126 <varlistentry>
127   <term>LOG_FILE</term>
128   <listitem>
129     <simpara>Nom du fichier de log des mises à jour.</simpara>
130   </listitem>
131 </varlistentry>
132
133 <varlistentry>
134   <term>THEME</term>
135   <listitem>
136     <simpara>Le nom du theme à installer (facultatif et non traité dans
137     ce tutoriel).</simpara>
138   </listitem>
139 </varlistentry>
140
141 <varlistentry>
142   <term>BUILD_DOC</term>
143   <listitem>
144     <simpara>Variable booléene définissant si la documentation doit être
145     compiler en utilisant le script <literal>buildDocExports.sh</literal>.
146     Ceci ne sera pas expliqué dans ce tutoriel et nous partirons donc du
147     principe que cette variable est à <literal>0</literal>.</simpara>
148   </listitem>
149 </varlistentry>
150
151 </variablelist>
152
153 <note><simpara>D'autres variables sont présentes dans ce fichier et
154 concerne uniquement la compilation de la documentation. Elle peuvent
155 être ignorée à partir du moment ou la variable
156 <literal>BUILD_DOC</literal> vaut <literal>0</literal>.</simpara></note>
157
158 <note><simpara>Il est possible d'utiliser dans ce fichier de configuration
159 la variable bash <literal>$ROOT_DIR</literal> correspondant au chemin
160 du dossier d'installation, c'est à dire dans notre exemple
161 <literal>/var/www/ldapsaisie</literal>.</simpara></note>
162   
163   </para>
164   </listitem>
165   
166   <listitem><simpara>La deuxième étape concerne la configuration globale
167   de l'application : Cette partie est principalement contenue dans le
168   fichier <emphasis>conf/config.inc.php</emphasis>. Il faut donc dans un
169   premier temps copier ce fichier dans le dossier <literal>config.local</literal>
170   et le déclarer dans la liste des fichiers à déployer lors des mises à
171   jour (variable <literal>LOCAL_FILES</literal> dans le fichier 
172   <literal>local.sh</literal>). Il s'agit en particulier dans ce fichier
173   de configurer la connexion à votre annuaire. Vous pouvez vous inspirer
174   du fichier d'exemple fourni et pour plus de détails, reportez-vous à
175   <link linkend="config-globale">la section concernée</link>.
176   </simpara>
177   <note><simpara>Notez qu'il est possible de passer l'application en mode
178   <emphasis>debug</emphasis> ce qui peut être utile par la suite.</simpara></note>
179   </listitem>
180   
181   <listitem><simpara>La troisième étape concerne la configuration des
182   types de &LSobjects; : Chaque type d'objet manipulé par LdapSaisie doit
183   correspondre avec un type de LSobject.</simpara>
184     
185     <orderedlist>
186     
187     <listitem><para>Création du fichier de classe : Ce fichier contient la 
188     déclaration de la classe PHP correspondant au type de LSobject. Cette classe
189     étend la classe <emphasis>LSldapObject</emphasis> qui contient pour ainsi dire
190     toute les méthodes et proprités nécessaires pour les types de LSobject simples
191     (sans &LSrelation;). Les fichiers des classes sont contenus dans le dossier
192     <emphasis>/includes/class/</emphasis> et portent les noms composés de la 
193     manière suivante : 
194     <programlisting>class.LSobjects.[nom du type d'LSobject].php</programlisting>
195     Le plus simple pour cette étape est de copier un des fichiers d'exemple dans
196     le dossier <literal>config.local</literal> et de l'adapter en changeant
197     le nom du type d'objet dans l'ensemble du fichier. Pour cela, le fichier
198     de classe du type <emphasis>LSpeople</emphasis> est le plus simple
199     car il ne contient que le strict minimum. Pour un fichier de classe
200     ayant des &LSrelations; à gérer, le fichier de classe <emphasis>LSgroup
201     </emphasis> contient déjà les méthodes nécéssaires pour gérer ces cas.
202     </para></listitem>
203     
204     <listitem><simpara>Configurer vos LSobject : Cette partie est certainement la
205     plus longue et consiste à déclarer l'ensemble des informations relatives aux
206     types des objets LDAP manipulés. Les fichiers d'exemples fournis vous seront
207     alors d'une aide précieuse. basé vous sur l'un de pour créer le votre. Pour
208     cela le fichier de configuration du type d'LSobjet <emphasis>LSpeople</emphasis>
209     est le plus complet et est un bon point de départ. Pour plus de détails sur les
210     élements de configuration de ce fichier, reportez-vous à 
211     <link linkend="config-LSobject">la section concernée</link>.</simpara>
212     </listitem>
213     
214     <listitem><simpara>Configurer si nécessaire les relations entre les objets
215     appelés &LSrelations;. Cette opération consiste dans un premier temps à écrire
216     les méthodes PHP nécessaires pour gérer ces relations : pour cela regardez le
217     fichier de classe du type <emphasis>LSgroup</emphasis>. Il faudra ensuite
218     déclarer ces relations dans la configuration des types d'LSobjects : Pour plus
219     de détails, reportez-vous à <link linkend="config-LSobject-LSrelation">la 
220     section concernée</link>.</simpara>
221     </listitem>
222     
223   </orderedlist>
224   
225   <important><simpara>Pensez à déclarer les fichiers que vous venez de créer dans la variable
226   <literal>LOCAL_FILES</literal> du fichier <literal>local.sh</literal>. Exemple pour le
227   type d'LSobjet portant comme nom <literal>LSexample</literal> :</simpara>
228 <programlisting>public_html/conf/LSobjects/config.LSobjects.LSexample.php
229 public_html/includes/class/class.LSobjects.LSexample.php</programlisting>
230   </important>
231   
232   <note><simpara>Vous pouvez également personnaliser l'interface : Il est
233   possible de personnaliser à votre goût l'interface en écrivant votre
234   template ou en modifiant simplement les fichiers CSS. Une partie de
235   cette documentation concernera bientôt cette problématique. Patience...
236   </simpara></note>
237   
238   </listitem>
239   
240   <listitem><simpara>La dernière étape à ce niveau consiste à lancer le script
241   <literal>upgradeFromGit.sh</literal> pour qu'il installe les fichiers
242   que vous venez de créer. Ce script est conçu pour dire tout ce qu'il fait
243   donc en cas de problème vous devriez rapidement comprendre où cela coince.
244   Dans tout les cas, n'hésitez pas à poser vos questions à la communauté sur
245   la liste <email>ldapsaisie-users@lists.labs.libre-entreprise.org</email>.
246   </simpara></listitem>
247   
248   <listitem><simpara>Vous devriez dès à présent accèder à l'application
249   via votre navigateur web à l'URL suivante :</simpara>
250   <programlisting>http://[IP ou nom du serveur]/ldapsaisie/public_html</programlisting>
251   </listitem>
252   
253 </orderedlist>
254
255
256
257 </sect1>
258  
259 </chapter>