Scarab commit: svn commit: r10424 - trunk/www/book
[email protected] 19 Feb 2007 15:37:19 -0000
Newsgroups
gmane.comp.java.scarab.cvs
Message-ID
<[email protected] >
Author: jfelfouly
Date: 2007-02-19 07:37:19-0800
New Revision: 10424
Modified:
trunk/www/book/install-en.xml
trunk/www/book/install-fr.xml
Log:
Updated the installation documentation to include the experimental web installer.
Modified: trunk/www/book/install-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/install-en.xml?view=diff&rev=10424&p1=trunk/www/book/install-en.xml&p2=trunk/www/book/install-en.xml&r1=10423&r2=10424
==============================================================================
--- trunk/www/book/install-en.xml (original)
+++ trunk/www/book/install-en.xml 2007-02-19 07:37:19-0800
@@ -67,7 +67,8 @@
</sect4>
<sect4>
<title>Oracle 9i</title>
- <para>The compatibility of Scarab with Oracle 9i has also been tested</para>
+ <para>The compatibility of Scarab 0.20 with Oracle 9i has been tested</para>
+ <para>The compatibility of Scarab 0.21 has not been tested, neither with Oracle 9 nor with Oracle 10 (10g or 10 XE). The Scarab development team plans to test and improve the Oracle compatibility in the current version (TRUNK). Feel free to discuss any question you have or any issue you encounter in the mailing lists.</para>
<para>Because of a problem with the manner Torque manages BLOBs, using Scarab with Oracle 9i is a bit more difficult than with other DBMS (you will have to patch the code generated by Torque).</para>
</sect4>
</sect3>
@@ -101,7 +102,7 @@
<sect3>
<title>Download and install a Java SDK</title>
<para>If you don't have a Java SDK handy (pre-installed on some systems such as MacOS X or certain Linux distributions), you need to download and install one. Be careful: you need a Java 2 SDK and not only a JRE (Java Runtime Environment) because you will need to compile Scarab.</para>
- <para>The SDK version must be at least 1.3.1.</para>
+ <para>The SDK version must be at least 1.4.</para>
<para>You may download a Java SDK from <ulink url="http://java.sun.com">http://java.sun.com</ulink>.</para>
<para>Make sure the JAVA_HOME environment variable correctly points to the directory in which your SDK is installed.</para>
</sect3>
@@ -590,7 +591,70 @@
</sect2>
</sect1>
<sect1>
- <title>Building Scarab</title>
+ <title>Building Scarab with the web install application</title>
+ <simpara>For a quick install, a test install or if you just want to experiment with Scarab, you will find the web installation simpler and much more user-friendly. This simplified process allows you to define the most current parameters and gives you short explanations and even some advice.</simpara>
+ <simpara>If you are a power user and want a fine-tuned installation or if your environment does not allow for the web installer, skip this section and install Scarab from the command line.</simpara>
+ <sect2>
+ <title>Step 1: Unpack the Scarab distribution</title>
+ <para>
+ The Scarab release can be downloaded as either a .zip or a .tar.gz file.
+ Unpack either one of these into a directory that you have write access
+ to.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Step 2 : Unpack the web installer</title>
+ <para>
+ Download the install application from the Scarab web site and unpack the web application at the same place you unpacked the Scarab distribution. You may be asked whether you accept to overwrite $SCARAB/tomcat/conf/web.xml : accept it.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Step 3: Configure and start Tomcat</title>
+ <simpara>With the default settings, Tomcat will start listening on the 8080 port. If this is a problem (e.g., because another program -- such as the Oracle XE admin application -- uses this port), edit the <computeroutput>$SCARAB/tomcat/conf/server.xml</computeroutput> file and change the port (line 3).</simpara>
+ <simpara>To start Tomcat, go to the <computeroutput>$SCARAB/tomcat/bin</computeroutput> directory and launch:</simpara>
+ <itemizedlist>
+ <listitem><simpara><computeroutput>startup.sh</computeroutput> (Unix)</simpara></listitem>
+ <listitem><simpara><computeroutput>startup.bat</computeroutput> (Windows)</simpara></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2>
+ <title>Step 4: Configure Scarab</title>
+ <simpara>Now launch your favorite web browser and go to the following URL: <ulink url="http://localhost:8080/ScarabWebInstaller">http://localhost:8080/ScarabWebInstaller</ulink></simpara>
+ <simpara>You'll see the "Basic settings" page..</simpara>
+ <graphic fileref="images/webinstall1.png"/>
+ <simpara>This web page has four forms. If you want to modify the default values for a parameter in a form, do not forget to save this setting using the "Submit" button (the settings are saved one block at a time and not page by page).</simpara>
+ <graphic fileref="images/webinstall2.png"/>
+ <simpara>You may navigate back and forth between the "Basic settings" and "Advanced settings" tabs. When you are finished configuring the application as you wish, scroll down to the bottom of a page and click <emphasis>Build Scarab now !</emphasis></simpara>
+ <graphic fileref="images/webinstall3.png"/>
+ <simpara>The application writes down your parameters in the <computeroutput>build.properties</computeroutput> file, located in the root directory of your installation, generates a shell script to invoke Ant and executes this script.</simpara>
+ <simpara>The result appears on the next page:</simpara>
+ <graphic fileref="images/webinstall4r.png"/>
+ <simpara>If this worked as expected, you can proceed and create the Scarab database using the "Build the Scarab database" button.</simpara>
+ <graphic fileref="images/webinstall5.png"/>
+ <simpara>The application writes a second shell script to invoke Ant and launches this script. The result appears on the last page.</simpara>
+ <graphic fileref="images/webinstall6r.png"/>
+ <simpara>If this last operation was a success, the installation is almost over, you have just some cleanup to perform. In fact, Scarab may have been launched already by Tomcat but you really should stop, purge and restart Tomcat.</simpara>
+ </sect2>
+ <sect2>
+ <title>Step 5: Stop Tomcat</title>
+ <para>To stop Tomcat, go to the <computeroutput>$SCARAB/tomcat/bin</computeroutput> directory and execute:</para>
+ <itemizedlist>
+ <listitem><simpara><computeroutput>shutdown.sh</computeroutput> (Unix)</simpara></listitem>
+ <listitem><simpara><computeroutput>shutdown.bat</computeroutput> (Windows)</simpara></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2>
+ <title>Step 6: Remove the web installer</title>
+ <simpara>The web installer is unprotected and leaving it there would certainly create a security issue. If you want to leave your Scarab installation in a clean state, uninstall the web installer by removing the <computeroutput>ScarabWebInstaller</computeroutput> directory under <computeroutput>$SCARAB/tomcat/webapps</computeroutput>.</simpara>
+ <simpara>(If you are a paranoid admin, you have probably kept the $SCARAB/tomcat/conf/web.xml file around. Otherwise you still may retrieve an original version from the Scarab distribution. But this is not stricty required.)</simpara>
+ </sect2>
+ <sect2>
+ <title>Step 7: Restart Tomcat and launch Scarab</title>
+ <simpara>You may now restart Tomcat as has been explained in the Step 3 above.</simpara>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Building Scarab: command-line installation</title>
<note>
<simpara>This section is a formatted copy of the INSTALL file at the root of the Scarab distribution.</simpara>
</note>
Modified: trunk/www/book/install-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/install-fr.xml?view=diff&rev=10424&p1=trunk/www/book/install-fr.xml&p2=trunk/www/book/install-fr.xml&r1=10423&r2=10424
==============================================================================
--- trunk/www/book/install-fr.xml (original)
+++ trunk/www/book/install-fr.xml 2007-02-19 07:37:19-0800
@@ -67,8 +67,9 @@
<para>PostgreSQL est disponible gratuitement et en open-source sur Linux et sur Windows.</para>
</sect4>
<sect4>
- <title>Oracle 9i</title>
- <para>La compatibilité de Scarab avec Oracle 9i est testée.</para>
+ <title>Oracle 9 et 10</title>
+ <para>La compatibilité de Scarab 0.20 avec Oracle 9i est testée.</para>
+ <para>La compatibilité de Scarab 0.21 avec Oracle 9i et 10 (10g ou 10 XE) n'a pas pu être testée. L'équipe de développement espère tester et améliorer la compatibilité de la version courante (TRUNK) avec Oracle. N'hésitez pas à nous faire part des questions ou problèmes rencontrés, par le biais des listes de diffusion.</para>
<para>En raison d'un problème lié à la gestion des BLOBs par Torque, la mise en oeuvre de Scarab sur Oracle 9i est un peu plus délicate que sur d'autres SGBD et nécessite de faire un petit patch du code généré.</para>
</sect4>
</sect3>
@@ -103,7 +104,7 @@
<sect3>
<title>Télécharger et installer un SDK Java</title>
<para>Si vous ne disposez pas d'un SDK Java (pré-installé sur certains systèmes, par exemple MacOS X), vous devez en installer un. Attention: vous avez besoin d'un SDK Java 2 [notez que l'appellation JDK est périmée] et pas seulement d'un JRE (Java Runtime Environment), car il vous faudra compiler Scarab.</para>
- <para>La version du SDK doit être au moins 1.3.1.</para>
+ <para>La version du SDK doit être au moins 1.4.</para>
<para>Vous pouvez télécharger un SDK à partir de <ulink url="http://www.java.com">http://www.java.com</ulink> ou <ulink url="http://java.sun.com">http://java.sun.com</ulink>.</para>
<para>Assurez-vous que la variable d'environnement JAVA_HOME pointe sur le répertoire dans lequel le SDK est installé.</para>
</sect3>
@@ -594,6 +595,69 @@
</sect3>
</sect2>
</sect1>
+ <sect1>
+ <title>Installer Scarab avec l'installeur web</title>
+ <simpara>Pour une installation de test, pour expérimenter avec Scarab et même pour la plupart des installations typiques, il est plus aisé d'utiliser l'installeur web. Celui-ci vous donne accès aux paramètres les plus courants avec une ou deux phrases d'explication ou un conseil lorsque c'est approprié.</simpara>
+ <simpara>Si vous souhaitez un paramétrage fin de Scarab ou si votre environnement ne permet pas l'utilisation de l'installeur web, passez à la section suivante et utilisez l'installation en ligne de commande.</simpara>
+ <sect2>
+ <title>Etape 1: Déballer la distribution de Scarab</title>
+ <para>
+ Une distribution de Scarab peut être téléchargée comme archive .zip ou .tar.gz.
+ Décompressez l'une ou l'autre de ces archives dans un répertoire pour lequel
+ vous avez les droits d'écriture.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Etape 2: Déballer l'installeur web</title>
+ <para>
+ Téléchargez l'installeur web depuis le site web de Scarab et décompressez-le dans le même répertoire que la distribution de Scarab. Il se peut que le système vous demande l'autorisation de réécrire le fichier $SCARAB/tomcat/conf/web.xml: acceptez.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Etape 3: Configurer et lancer Tomcat</title>
+ <para>Par défaut, Tomcat va démarrer sur le port 8080. Si cette valeur ne vous convient pas parce qu'un autre programme utilise ce port (par exemple l'application d'administration d'Oracle XE s'il est sur la même machine), vous devez éditer le fichier $SCARAB/tomcat/conf/server.xml et modifier le port à la ligne 3.</para>
+ <para>Pour démarrer Tomcat, rendez-vous dans le répertoire $SCARAB/tomcat/bin et exécutez :</para>
+ <itemizedlist>
+ <listitem><simpara><computeroutput>startup.sh</computeroutput> (Unix)</simpara></listitem>
+ <listitem><simpara><computeroutput>startup.bat</computeroutput> (Windows)</simpara></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2>
+ <title>Etape 4: Configurer Scarab</title>
+ <simpara>Lancez votre navigateur et faites-le pointer vers l'URL <ulink url="http://localhost:8080/ScarabWebInstaller">http://localhost:8080/ScarabWebInstaller</ulink></simpara>
+ <simpara>Vous arrivez sur la page "Paramétrage de base".</simpara>
+ <graphic fileref="images/webinstall1.fr.png"/>
+ <simpara>Cette page contient quatre formulaires. Si vous souhaitez modifier les valeurs par défaut proposées dans un formulaire, pensez à le valider en cliquant le bouton Enregistrer (la prise en compte des modifications se fait groupe logique par groupe logique, pas globalement sur la page).</simpara>
+ <graphic fileref="images/webinstall2.fr.png"/>
+ <simpara>Vous pouvez aller et venir entre l'onglet "Paramétrage de base" et l'onglet "Paramétrage avancé". Lorsque vous avez terminé de configurer l'application comme vous le souhaitez, allez en bas d'une des deux pages et cliquez <emphasis>Construire Scarab</emphasis>.</simpara>
+ <graphic fileref="images/webinstall3.fr.png"/>
+ <simpara>Le système va enregistrer votre paramétrage dans le fichier <computeroutput>build.properties</computeroutput> situé à la racine de votre installation puis générer un script pour invoquer Ant et lancer ce script.</simpara>
+ <simpara>Le résultat de l'exécution de Ant apparaît sur la page suivante :</simpara>
+ <graphic fileref="images/webinstall4r.fr.png"/>
+ <simpara>Si l'opération s'est déroulée correctement, vous pouvez passer à la création de la base de données en cliquant le bouton <emphasis>Construire la base de données Scarab</emphasis>.</simpara>
+ <graphic fileref="images/webinstall5.fr.png"/>
+ <simpara>Le système va à nouveau créer un script pour invoquer Ant et lancer ce script. Le résultat de l'exécution apparaît à la dernière page.</simpara>
+ <graphic fileref="images/webinstall6r.fr.png"/>
+ <simpara>Si cette dernière opération s'est déroulée correctement, l'installation est pratiquement terminée, il ne vous reste plus qu'un peu de ménage à faire. A ce stade, l'application Scarab a peut-être déjà été lancée automatiquement par Tomcat mais il est préférable de faire un arrêt / purge / relance.</simpara>
+ </sect2>
+ <sect2>
+ <title>Etape 5: Arrêter Tomcat</title>
+ <para>Pour arrêter Tomcat, rendez-vous dans le répertoire $SCARAB/tomcat/bin et exécutez :</para>
+ <itemizedlist>
+ <listitem><simpara><computeroutput>shutdown.sh</computeroutput> (Unix)</simpara></listitem>
+ <listitem><simpara><computeroutput>shutdown.bat</computeroutput> (Windows)</simpara></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2>
+ <title>Etape 6: Enlever l'installeur</title>
+ <simpara>Pour ne pas créer de risque de sécurité et laisser votre installation de Scarab dans un état propre, désinstallez l'application web d'installation en supprimant le dossier ScarabWebInstaller sous <computeroutput>$SCARAB/tomcat/webapps</computeroutput>.</simpara>
+ <simpara>(Si vous êtes un administrateur paranoïaque, vous avez peut-être mis de côté le fichier $SCARAB/tomcat/conf/web.xml; sinon vous pouvez toujours réinstaller la version originale de ce fichier à partir de la distribution de Scarab. Mais ce n'est pas vraiment nécessaire.)</simpara>
+ </sect2>
+ <sect2>
+ <title>Etape 7: Redémarrer Tomcat et lancer Scarab</title>
+ <simpara>Vous pouvez à présent redémarrer Tomcat en procédant comme à l'étape 3 ci-dessus.</simpara>
+ </sect2>
+ </sect1>
<sect1>
<title>Construire Scarab</title>
<note>
@@ -605,7 +669,7 @@
Une distribution de Scarab peut être téléchargée comme archive .zip ou .tar.gz.
Décompressez l'une ou l'autre de ces archives dans un répertoire pour lequel
vous avez les droits d'écriture.
- </para>
+ </para>
</sect2>
<sect2>
<title>Etape 2: Migration d'une ancienne version de Scarab (pre-19)</title>
@@ -653,6 +717,7 @@
<title>Paramétrage du jeu de caractères utilisé pour le courrier électronique</title>
<para>Vous devez pour cela définir la propriété scarab.email.encoding, par exemple</para>
<para>scarab.email.encoding=ISO-8859-1</para>
+ <para>scarab.email.encoding=ISO-8859-15 (support du caractère Euro)</para>
<para>scarab.email.encoding=UTF-8</para>
<para>Le courrier électronique fonctionnera probablement sans ce réglage mais vous risquez de voir les noms d'utilisateur précédés de préfixes linguistiques particulièrement inesthétiques.</para>
</sect4>