Add import feature
[ldapsaisie.git] / public_html / INSTALL
index 8563149..8b3693f 100644 (file)
- INSTALLATION
-===================
 
 
-1. Pré-requis
-=============
+  /========================\
+  |      INSTALLATION      |
+  \========================/
 
 
-    * PHP 5 avec magic_quotes_gpc à off
-    * Le support LDAP dans PHP (paquet php5-ldap dans Debian)
-    * Le support mhash dans PHP (paquet php5-mash dans Debian)
-    * Net_LDAP2
-    * Smarty
-    * L'utisateur exécutant le serveur web doit avoir les droits d'écriture sur le dossier 'tmp'.
 
 
-[Avertissement]
+1. Pré-requis
+=============
 
 
-La librairie Net_LDAP2 oblige le fait que la racine DSE de l'annuaire soit lisible en anonyme sinon la connexion à l'annuaire échouera systématiquement.
+ * PHP 5 avec magic_quotes_gpc et register_globals à off
+ * Le support LDAP dans PHP (paquet php5-ldap dans Debian)
+ * Le support mhash dans PHP (paquet php5-mhash dans Debian)
+ * Le support json dans PHP (pear install pecl/json sur RedHat, dans common sur Debian)
+ * Net_LDAP2 (pear install net_ldap2)
+ * Smarty (paquet smarty dans Debian)
+ * L'utisateur exécutant le serveur web doit avoir les droits d'écriture sur le dossier 'tmp'.
+   
+  #################
+  # Avertissement #
+  #################
+  #
+  # La librairie Net_LDAP2 oblige le fait que la racine DSE de l'annuaire soit lisible en anonyme sinon la connexion à l'annuaire échouera systématiquement.
+  #
 
 
 2. Téléchargement
 =================
 
 
 
 2. Téléchargement
 =================
 
-Il n'existe pas encore de version stable publiée. Vous pouvez obtenir le code source soit en le rapatriant à partir du serveur Subversion, soit en téléchargeant le dernier snapshot nocturne de l'arbre Subversion.
+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.
 
 
-2.1. A partir de Subversion
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+2.1. A partir de Git
+--------------------
 
 
-Le dépôt Subversion peut être récupéré anonymement en utilisant la commande suivante :
+Le dépôt Git peut être récupéré anonymement en utilisant la commande suivante :
 
 
-      svn checkout svn://labs.libre-entreprise.org/svnroot/ldapsaisie
+      git clone git://git.labs.libre-entreprise.org/ldapsaisie.git
     
     
-
-La racine web de l'application se trouvera alors dans le dossier /ldapsaisie/trunk/.
+La racine web de l'application se trouvera alors dans le dossier /ldapsaisie/public_html/.
 
 2.2. A partir des snapshot
 
 2.2. A partir des snapshot
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Toutes les nuits, un snapshot de l'arbre Subversion est réalisé et est téléchargeable au format tar.gz à l'adresse suivante : http://labs.libre-entreprise.org/snapshots.php?group_id=118
+--------------------------
 
 
+Toutes les nuits, un snapshot de l'arbre Git est réalisé et est téléchargeable au format tar.gz à l'adresse suivante : http://ldapsaisie.easter-eggs.org/download/ldapsaisie-snapshoot.tar.gz
 
 3. Arborescence du projet
 =========================
 
 Racine
 
 
 3. Arborescence du projet
 =========================
 
 Racine
 
-conf/
+doc/
+    Les fichiers sources de la documentation (docbook).
+lsexample/
+    Les fichiers relatifs à l'annuaire d'exemple.
+public_html/
+    Racine Web.
 
 
-    Contient les fichiers de configuration.
+    conf/
 
 
-    LSobjects/
-        Configuration des LSobjets.
-    LSaddons/
-        Configuration des LSaddons.
+        Contient les fichiers de configuration.
 
 
-includes/
+        LSobjects/
+            Configuration des LSobjects.
+        LSaddons/
+            Configuration des LSaddons.
+        LSauth/
+            Configuration des LSauth.
 
 
-    Contient les fichiers des ressources.
+    includes/
 
 
-    addons/
-        Les addons au projet.
-    class/
-        Les fichiers de définition des classes PHP.
-    js/
-        Les fichiers Javascript.
-    libs/
-        Les librairies utilisées.
+        Contient les fichiers des ressources.
 
 
-l10n/
-    Les fichiers d'internationalisation.
-lsexample/
-    Les fichiers relatifs à l'annuaire d'exemple.
-templates/
-    Les fichiers template de l'interface. Il y a un sous-dossier par template.
-css/
-    Les fichiers css de l'interface. Il y a un sous-dossier par template CSS.
-images/
-    Les images de l'interface. Il y a un sous-dossier par template d'image.
-tmp/
-    Les fichiers temporaires (y compris le cache des templates).
+        addons/
+            Les addons au projet.
+        class/
+            Les fichiers de définition des classes PHP.
+        js/
+            Les fichiers Javascript.
+        libs/
+            Les librairies utilisées.
+
+    lang/
+
+        Les fichiers d'internationalisation.
+
+    templates/
+
+        Les fichiers template de l'interface. Il y a un sous-dossier par template.
+
+    css/
+
+        Les fichiers css de l'interface. Il y a un sous-dossier par template CSS.
+
+    images/
+
+        Les images de l'interface. Il y a un sous-dossier par template d'image.
+
+    tmp/
+
+        Les fichiers temporaires (y compris le cache des templates).
+
+
+4. Tutoriel d'installation
+==========================
+
+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.
+
+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 /var/www/ldapsaisie. 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 lsexample.
+
+ 1. 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 git-core. Le dépôt Git doit ensuite être récupéré anonymement en utilisant la commande suivante :
+
+    git clone git://git.labs.libre-entreprise.org/ldapsaisie.git
+  
+  ########
+  # Note #
+  ########
+  #
+  # 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.
+  #
+
+La suite des opérations se déroulera donc maintenant dans le dossier /var/www/ldapsaisie. Pour avoir plus de détails sur les élements qu'on retrouve dans ce dossier, vous pouvez consulter la documentation du projet. [1]. Nous allons nous instérésser plus particulièrement :
+
+ * au script upgradeFromGit.sh permettant la mise à jour de votre repos tout en concervant les adaptations que nous ferons pour l'usage d'LdapSaisie adapté à notre annuaire ;
+ * au dossier config.local dans lequel seront stockés vos fichiers et vos adaptations de l'application ;
+ * au dossier public_html qui correspond à la futur racine du site web de l'application.
+
+Le principe de l'adaptation est ici de mettre vos fichiers personnalisés dans le dossier config.local, de les déclarer dans votre fichier config.local/local.sh contenant la liste des fichiers devant être installés. Le fichier local.sh est la source de configuration du script upgradeFromGit.sh. Il faut donc dans un premier temps créer votre fichier local.sh en copiant le fichier d'example local.sh.example. Ce fichier est un script bash déclarant les variables de configurations suivantes :
+
+LOCAL_FILES
+  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 :
+
+    public_html/conf/config.inc.php
+    public_html/lang/fr_FR.UTF8/lang.php
+
+LOG_FILE
+  Nom du fichier de log des mises à jour.
+
+THEME
+  Le nom du theme à installer (facultatif et non traité dans ce tutoriel).
+
+BUILD_DOC
+  Variable booléene définissant si la documentation doit être compiler en utilisant le script buildDocExports.sh. Ceci ne sera pas expliqué dans ce tutoriel et nous partirons donc du principe que cette variable est à 0.
+
+  ########
+  # Note #
+  ########
+  #
+  #   * 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 BUILD_DOC vaut 0.
+  #
+  #   * Il est possible d'utiliser dans ce fichier de configuration la variable bash $ROOT_DIR correspondant au chemin du dossier d'installation, c'est à dire dans notre exemple /var/www/ldapsaisie.
+  #
+
+ 2. La deuxième étape concerne la configuration globale de l'application : Cette partie est principalement contenue dans le fichier conf/config.inc.php. Il faut donc dans un premier temps copier ce fichier dans le dossier config.local et le déclarer dans la liste des fichiers à déployer lors des mises à jour (variable LOCAL_FILES dans le fichier local.sh). 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, consulter la documentation du projet. [1]
+
+  ########
+  # Note #
+  ########
+  #
+  # Notez qu'il est possible de passer l'application en mode debug ce qui peut être utile par la suite.
+  #
+
+ 3. 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.
+
+    a. 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 LSldapObject 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 /includes/class/ et portent les noms composés de la manière suivante :
 
 
+    class.LSobjects.[nom du type d'LSobject].php
 
 
-4. Les étapes de l'installation
-===============================
+Le plus simple pour cette étape est de copier un des fichiers d'exemple dans le dossier config.local 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 LSpeople 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 LSgroup contient déjà les méthodes nécéssaires pour gérer ces cas.
 
 
-Cette section décrit rapidement les différentes étapes de l'installation de LdapSaisie.
+    b. 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 LSpeople 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, consulter la documentation du projet. [1]
 
 
-   1. Téléchargement et décompression si nécessaire. (Cf : 2. Téléchargement)
+    c. 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 LSgroup. Il faudra ensuite déclarer ces relations dans la configuration des types d'LSobjects : Pour plus de détails, consulter la documentation du projet. [1]
 
 
-   2. Configuration globale : Cette partie est principalement contenue dans le fichier conf/config.inc.php. Il s'agit en particulier de configurer la connexion à votre annuaire. Pour plus de détails, consulter la documentation du projet. [1]
+  #############
+  # Important #
+  #############
+  #
+  # Pensez à déclarer les fichiers que vous venez de créer dans la variable LOCAL_FILES du fichier local.sh. Exemple pour le type d'LSobjet portant comme nom LSexample :
+  #
+  #     public_html/conf/LSobjects/config.LSobjects.LSexample.php
+  #     public_html/includes/class/class.LSobjects.LSexample.php
+  #
 
 
-      [Note]
-      Il est possible de passer l'application en mode debug ce qui peut être utile par la suite.
+  ########
+  # Note #
+  ########
+  #
+  # 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...
+  #
 
 
  3. Configuration des types de LSobjects : Chaque type d'objet manipulé par LdapSaisie doit correspondre avec un type de LSobject.
4. La dernière étape à ce niveau consiste à lancer le script upgradeFromGit.sh 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 <ldapsaisie-users@lists.labs.libre-entreprise.org>.
 
 
-         1. 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 LSldapObject 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 /includes/class/ et portent les noms composés de la manière suivante :
 
 
-            class.LSobjects.[nom du type d'LSobject].php
+ 5. Vous devriez dès à présent accèder à l'application via votre navigateur web à l'URL suivante :
 
 
-            Le plus simple pour cette étape est de recopier un des fichiers d'exemple 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 LSpeople est le plus simple car il ne contient que le strict minimum.
+     http://[IP ou nom du serveur]/ldapsaisie/public_html
 
 
-         2. 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 certainement d'une aide précieuse. Pour plus de détails, consulter la documentation du projet. [1]
 
 
-         3. 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 LSgroup. Il faudra ensuite déclarer ces relations dans la configuration des types d'LSobjects : Pour plus de détails, consulter la documentation du projet. [1]
 
 
-   4. 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...
 
 Liens
 =====
 
 Liens
 =====