Scarab commit: svn commit: r10202 - trunk/www/book
[email protected] 6 Jul 2006 15:49:51 -0000
Newsgroups
gmane.comp.java.scarab.cvs
Message-ID
<[email protected] >
Author: jfelfouly
Date: 2006-07-06 08:49:50-0700
New Revision: 10202
Modified:
trunk/www/book/install-en.xml
trunk/www/book/install-fr.xml
Log:
Replaced MySQL stuff by the detailed explanation Hussayn Dabbous wrote in the Wiki.
Modified: trunk/www/book/install-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/install-en.xml?view=diff&rev=10202&p1=trunk/www/book/install-en.xml&p2=trunk/www/book/install-en.xml&r1=10201&r2=10202
==============================================================================
--- trunk/www/book/install-en.xml (original)
+++ trunk/www/book/install-en.xml 2006-07-06 08:49:50-0700
@@ -125,89 +125,276 @@
<para>Make sure the ANT_HOME environment variable correctly points to the directory in which Ant is installed</para>
</sect3>
<sect3>
- <title>Downlad Scarab</title>
- <para>You need of course to download Scarab itself. You will find the latest version (1.0-b18) at the following URL: <ulink url="http://scarab.tigris.org/servlets/ProjectDocumentList">http://scarab.tigris.org/servlets/ProjectDocumentList</ulink>.</para>
+ <title>Download Scarab</title>
+ <para>You need of course to download Scarab itself. You will find the latest version (1.0-b21) at the following URL: <ulink url="http://scarab.tigris.org/servlets/ProjectDocumentList">http://scarab.tigris.org/servlets/ProjectDocumentList</ulink>.</para>
</sect3>
</sect2>
</sect1>
<sect1>
- <title>Installing the database software and preparing for Scarab installation</title>
+ <title>Installing and configuring MySQL</title>
<sect2>
- <title>MySQL</title>
+ <title>Guide for Linux with RPM packages</title>
<sect3>
- <title>Installing MySQL</title>
- <para>Please refer to the MySQL installation instructions.</para>
+ <title>Grab the MySQL distribution</title>
+ <simpara>You will find an appropriate distribution through the <ulink url="|http://www.mysql.com">MySQL website</ulink>.</simpara>
+ <simpara>You can follow the instructions from the MySQL documentation. We shall give here summary info only.</simpara>
</sect3>
<sect3>
- <title>Create a database user for Scarab</title>
- <para>You will not be able (or you won't like) to run Scarab with the default MySQL security scheme (root user without password on the local machine).</para>
- <para>So, you'll probably need to create a MySQL user and grant him/her the appropriate rights. Let's suppose you want to create a database user with the name 'scarab' on a local server et grant him the rights on a 'scarab' database; connect to the admin interface (the unix command is <computeroutput>mysql</computeroutput>) and execute the following statement :</para>
- <para>
- <computeroutput>grant all privileges on scarab.* to scarab@localhost;</computeroutput>
- </para>
- <para>
- <computeroutput>flush privileges;</computeroutput>
- </para>
- <para>If you want the 'scarab' user to authenticate with the password 'secret' when he/she/it connects to the database server, the syntax becomes </para>
- <para>
- <computeroutput>grant all privileges on scarab.* to scarab@localhost identified by 'secret';</computeroutput>
- </para>
- <para>
- <computeroutput>flush privileges;</computeroutput>
- </para>
- </sect3>
- <sect3>
- <title>Setting up the MySQL parameters in Scarab</title>
- <para>Use a text or program editor to open read-only (if possible) the default properties file in the build directory of your Scarab installation. Do not modify this file.</para>
- <para>Use your editor to create a build.properties file in the same directory. Any parameter you will define in this file will take precedence on the one defined in default.properties. This allows you to keep reasonable default values for most parameters while redefining those you want (or must) change.</para>
- <sect4>
- <title>Define the database type</title>
- <para>You do not need to redefine the scarab.database.type parameter, because by default (as you can see by yourself in the default.properties file):</para>
- <para>scarab.database.type=mysql</para>
- </sect4>
- <sect4>
- <title>Define the database user</title>
- <para>Even in a default MySQL installation, you will probably have to define the database user (scarab.database.username), for instance:</para>
- <para>scarab.database.username=scarab</para>
- <para>If a password is required for this database user, you will also need to define the scarab.database.password key, for instance:</para>
- <para>scarab.database.password=secret</para>
- </sect4>
- <sect4>
- <title>Define the database server</title>
- <para>By default, the database is supposed to be on the same machine as the Scarab server:</para>
- <para>scarab.database.host=127.0.0.1</para>
- <para>If the database server isn't on the same machine as the servlet engine, you need to define the scarab.database.host ky, specifying the network name of the MySQL server or its IP address.</para>
- <para>If you are faced to database access errors to a local database (access denied), you may try to replace 127.0.0.1 by localhost.</para>
- </sect4>
+ <title>Install the distribution</title>
+ <simpara>For example if you have grabbed version 4.0.22, you can install MySQL as follows:</simpara>
+ <informalexample>
+ <programlisting>
+ rpm -i MySQL-server-4.0.22-0.i386.rpm MySQL-shared-4.0.22-0.i386.rpm MySQL-client-4.0.22-0.i386.rpm
+ </programlisting>
+ </informalexample>
</sect3>
<sect3>
- <title>Option: downloading an optimized driver</title>
- <para>If you build a "production" Scarab installation, you may choose to use a MySQL driver that is more recent and more performant than the one supplied in the Scarab distribution (this driver may not be bundled with Scarab because its licence is GPL).</para>
- <para>Download this driver from the MySQL web site at the following URL: <ulink url="http://www.mysql.com/downloads/api-jdbc-dev.html">http://www.mysql.com/downloads/api-jdbc-dev.html</ulink> and copy the jar in the lib directory of your Scarab installation.</para>
- <para>You also need to declare its use in your build.properties file:</para>
- <para>scarab.database.jdbc.driver.jar=mysql-connector*.jar</para>
+ <title>Initialize and setup your database server</title>
+ <simpara>Install the root database first and start the mysql-daemon. This step is apparently not required, because installing the rpm's already processes these steps. But just in case they don't, you can do manually:</simpara>
+ <informalexample>
+ <programlisting>
+mysql_install_db
+safe_mysqld
+ </programlisting>
+ </informalexample>
</sect3>
</sect2>
<sect2>
- <title>PostgreSQL</title>
+ <title>Configuring MySQL for Scarab</title>
+ <simpara>The following cookbook approach summarizes the process of tracking down connection problems with MySQL __and__ Scarab which almost ever turn out to be a matter of incorrectly configured privileges. I assume you have a clean MySQL installation on your system and you want to run the MySQL database and scarab on the same host namely <computeroutput>localhost</computeroutput>. Each step below goes into some degree of detail. Maybe not all described steps are necessary in your environment.</simpara>
<sect3>
- <title>Installing PostgreSQL</title>
- <para>Please refer to the PostgreSQL installation instructions.</para>
+ <title>Step I (unix only) - Check the /etc/hosts file</title>
+ <simpara>If you plan to run MySQL on localhost, you must check the corresponding entry in your /etc/hosts file. We have seen problems when the localhost entry is defined as in the following example:</simpara>
+ <informalexample>
+ <programlisting>
+127.0.0.1 localhost.localdomain localhost (seen on debian)
+127.0.0.1 linux localhost (seen on Suse)
+ </programlisting>
+ </informalexample>
+ <simpara>If you see similar entries, revert the order so that "localhost" appears first:</simpara>
+ <informalexample>
+ <programlisting>
+127.0.0.1 localhost localhost.localdomain (seen on debian)
+127.0.0.1 localhost linux (seen on Suse)
+ </programlisting>
+ </informalexample>
+ <simpara>You may need to reboot(!) although I am not sure about this. After reboot, ensure that your operating system has not manipulated the entry in your /etc/hosts file. I have no idea what to do if this happens... (FIXME: add a recipe for this situation)
+</simpara>
</sect3>
<sect3>
- <title>Setting up the PostgreSQL in Scarab</title>
- <para/>
+ <title>Step II - Ensure MySQL is up and running</title>
+ <simpara>I assume you have just installed an instance of MySQL. MySQL comes with an administration user named "root" and with no password at all. Yes, this is highly insecure. However it helps getting started with MySQL quickly. We will come back to security in the next step.</simpara>
+ <simpara>For now just try to enter the database administration. You may do so from a commandline (dos box or windows shell):</simpara>
+ <simpara>
+ <computeroutput>mysql -u root mysql</computeroutput>
+ </simpara>
+ <simpara>Now you should have access to the administration database of your MySQL instance. If you are rejected, something out of the trail happened. Either your database is corrupted or someone else has installed the database and has set up security. In that case you may need to ask your administrator to give you access to the "mysql" database in order to proceed with the next step.</simpara>
+ </sect3>
+ <sect3>
+ <title>Step III - Secure your MySQL instance (optional)</title>
+ <simpara>Once you are logged in to the database either as root, or as some administrator (depending on your site) you can check the grants:</simpara>
+ <informalexample>
+ <programlisting>
+select host, user, password from user;
+
+ +-----------+------+----------+
+ | host | user | password |
+ +-----------+------+----------+
+ | localhost | root | |
+ +-----------+------+----------+
+ 1 row in set (0.01 sec)
+ </programlisting>
+ </informalexample>
+ <simpara>Now let's secure it. First, we want to secure the root user. Thus we give him/her a password, we choose "secret" here.</simpara>
+ <note>
+ <simpara>This step is NOT necessary to get Scarab up and running, so if you don't want to secure your database now, just don't execute the following statement.</simpara>
+ </note>
+ <informalexample>
+ <programlisting>
+grant all on *.* to root@localhost identified by 'secret';
+ </programlisting>
+ </informalexample>
+ <simpara>From now on you MUST remember your password for ever! The user table now looks as follows:</simpara>
+ <informalexample>
+ <programlisting>
+select host, user, password from user;
++-----------+------+-------------------------------------------+
+| host | user | password |
++-----------+------+-------------------------------------------+
+| localhost | root | *14E65567ABDB5135D0CFD9A70B3032C179A49EE7 |
++-----------+------+-------------------------------------------+
+1 row in set (0.00 sec)
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Step IV - Add the admin user for Scarab</title>
+ <simpara>We choose <emphasis>admin</emphasis> as administrator using the password <emphasis>secret</emphasis> and furthermore we choose the database name to be <emphasis>scarab</emphasis>. Of course you can take your own choice. </simpara>
+ <note>
+ <simpara>You will need ALL choices above later to add them to the {{build.properties}} of Scarab !</simpara>
+ </note>
+ <informalexample>
+ <programlisting>
+ grant all on scarab.* to admin@localhost identified by 'secret';
+ grant grant option on scarab.* to admin@localhost;
+ grant all on mysql.* to admin@localhost;
+ </programlisting>
+ </informalexample>
+ <note>
+ <simpara>You need the second statement because the admin user will eventually create the runtime database user! (see below) The term <computeroutput>grant grant option</computeroutput> above is definitely correct! You also will need the third statement because your scarab user uses a password for identification. In order to be able to make the appropriate settings, the admin needs access to the mysql control tables.</simpara>
+ </note>
+ <simpara>This is how the user table looks like now:</simpara>
+ <informalexample>
+ <programlisting>
+select host, user, password from user;
++-----------+--------+-------------------------------------------+
+| host | user | password |
++-----------+--------+-------------------------------------------+
+| localhost | root | *14E65567ABDB5135D0CFD9A70B3032C179A49EE7 |
+| localhost | admin | *14E65567ABDB5135D0CFD9A70B3032C179A49EE7 |
++-----------+--------+-------------------------------------------+
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Step V - Test the settings</title>
+ <caution>
+ <simpara>For safety keep the current shell open and DO NOT QUIT the mysql session. That helps if something went wrong ;-)</simpara>
+ </caution>
+ <simpara>OK, now open a new shell and try to create a database from the admin user:</simpara>
+ <informalexample>
+ <programlisting>
+mysqladmin -u admin -h localhost -p create scarab
+Enter password: ******
+ </programlisting>
+ </informalexample>
+ <simpara>Now you have created your scarab database, though it's empty. If the database was already there you would have received an appropriate error message! In that case don't proceed until you have checked where this database came from!</simpara>
+ <note>
+ <simpara>This step is NOT required for the Scarab setup, but doing so ensures that your privilege settings for the Scarab administration user are correct and work as needed. </simpara>
+ </note>
</sect3>
- </sect2>
- <sect2>
- <title>Oracle 9i</title>
<sect3>
- <title>Installing Oracle 9i</title>
- <para>Please refer to the Oracle 9i installation instructions.</para>
+ <title>Step VI - Configure scarab
+ </title>
+ <simpara>Make a copy of minimal.properties (or project.properties) and name it build.properties. You will need to define a runtime database user for your instance now. Let's choose "scarab" as username and "baracs" as password. These two properties will be needed now in addition to the admin user created in step IV above (just keep them in mind for a minute)</simpara>
+ <simpara>Now edit build.properties. About the database settings, please get hands on these properties:</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.username=scarab #changed from **GENERATED**
+scarab.database.password=baracs #changed from **GENERATED**
+scarab.database.admin.username=admin #changed from **GENERATED**
+scarab.database.admin.password=secret #changed from **GENERATED**
+scarab.database.host=localhost #unchanged
+scarab.database.name=scarab #unchanged
+ </programlisting>
+ </informalexample>
+ <simpara>Just to be complete: there are other relevant properties, but usually they are generated from the above settings. The only two additional properties you should take care of are:</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.type=mysql #unchanged
+scarab.database.port=**GENERATED** #unchanged
+ </programlisting>
+ </informalexample>
+ <simpara>Where the first one is set to mysql by default and the last one is set to the standard port 3306 used by MySQL for the connection peer.</simpara>
+ <note>
+ <simpara>The database.username and password are later used to automatically create(!) an additional user 'scarab' with password 'baracs'. So don't bother yourself with setting up other users except the admin user !</simpara>
+ </note>
</sect3>
<sect3>
- <title>Setting up the Oracle 9i parameters in Scarab</title>
- <para/>
+ <title>Step VII - Build scarab</title>
+ <simpara>Go to the build directory and launch ant</simpara>
+ <informalexample>
+ <programlisting>
+ ant
+ ant create-db
+ </programlisting>
+ </informalexample>
+ <simpara>This should execute without any error now. You should see something like this in the shell:</simpara>
+ <informalexample>
+ <programlisting>
+ [echo]
+ [echo] _________R U N T I M E B U I L D ___.
+ [echo] / _____/ ____ _____ ____________ \_ |__
+ [echo] \_____ \_/ ___\\__ \\_ __ \__ \ | __ \
+ [echo] / \ \___ / __ \| | \// __ \| \_\ \
+ [echo] /_______ /\___ >____ /__| (____ /___ /
+ [echo] \/ \/ \/ \/ \/
+ [echo]
+ [echo] [1.0-b20-200605092134]
+ [echo]
+ [echo]
+ [echo] Running with following options:
+ [echo]
+ [echo] database name = scarab
+ [echo] database type = mysql
+ [echo] jdbc driver = org.gjt.mm.mysql.Driver
+ [echo] database url = jdbc:mysql://localhost:3306/scarab?
+ [echo] host = localhost
+ [echo] port = 3306
+ [echo] username = scarab
+ [echo] admin user = Administrator
+ [echo]
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Rebuild Scarab after failure</title>
+ <simpara>The whole property settings have been copied from the build environment, thus the configuration may be invalid. In order to fix this you must regenerate the configuration (not the class files!). You can use ant for this:</simpara>
+ <informalexample>
+ <programlisting>
+cd build
+ant create-custom-property-file
+ </programlisting>
+ </informalexample>
+ <simpara>But definitely the safest way to proceed is simply rebuilding everything:</simpara>
+ <informalexample>
+ <programlisting>
+ant clean
+ant
+ant create-db
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Troubleshooting</title>
+ <sect4>
+ <title>If nothing helps</title>
+ <simpara>Here are a couple of additional links to help you solve the permissions problem:</simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <ulink url="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Access_denied">MySQL documentation</ulink>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <ulink url="http://sourceforge.net/docman/display_doc.php?docid=8968&group_id=15923">sourceforge</ulink>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </sect4>
+ <sect4>
+ <title>Last resort (applies to some linux distros)</title>
+ <para>
+ If nothing helps, check this (thanks to Josh Howe for investigation).
+ MySQL Connector/J can only communicate with MySQL using TCP/IP, as Java
+ does not support Unix domain sockets. TCP/IP communication with MySQL
+ may be affected if MySQL was started with the "--skip-networking"
+ flag or if it is firewalled.
+ </para>
+ <para>
+ If MySQL has been started with the "--skip-networking" option set (the
+ Debian Linux package of MySQL server does this for example), you need to
+ comment it out in the file /etc/mysql/my.cnf or /etc/my.cnf. Of course
+ your my.cnf file might also exist in the "data" directory of your MySQL
+ server, or anywhere else (depending on how MySQL was compiled for your
+ system). Binaries created by MySQL AB always look in /etc/my.cnf and
+ [datadir]/my.cnf. If your MySQL server has been firewalled, you will
+ need to have the firewall configured to allow TCP/IP connections from
+ the host where your Java code is running to the MySQL server on the port
+ that MySQL is listening to (by default, 3306).
+ </para>
+ </sect4>
</sect3>
</sect2>
</sect1>
@@ -251,8 +438,12 @@
In all other cases minimal.properties is your best choice (believe us!).
So most of you will be doing this:
</simpara>
- <simpara><computeroutput>cd $SCARAB_HOME</computeroutput></simpara>
- <simpara><computeroutput>cp minimal.properties build.properties</computeroutput></simpara>
+ <simpara>
+ <computeroutput>cd $SCARAB_HOME</computeroutput>
+ </simpara>
+ <simpara>
+ <computeroutput>cp minimal.properties build.properties</computeroutput>
+ </simpara>
</listitem>
<listitem>
<simpara>
@@ -278,7 +469,7 @@
<simpara>maven war -Dmaven.test.skip</simpara>
<note>
<simpara>
- <computeroutput>-Dmaven.test.skip</computeroutput> avoids running the junit tests.
+ <computeroutput>-Dmaven.test.skip</computeroutput> avoids running the junit tests.
If you want to run also the tests, simply enter
"maven war" and the tests will be performed. Prepare
for a significant amount of additional processing time!
@@ -334,10 +525,16 @@
can pass the option "-Dskip.jira.templates.data=true" to ant or maven,
e.g.
</simpara>
- <simpara><computeroutput>ant -Dskip.jira.templates.data=true create-db</computeroutput></simpara>
+ <simpara>
+ <computeroutput>ant -Dskip.jira.templates.data=true create-db</computeroutput>
+ </simpara>
<simpara>or</simpara>
- <simpara><computeroutput>maven -Dskip.jira.templates.data=true scarab:create-db</computeroutput></simpara>
- <note><simpara>This option is independent of 'skip.seed.data', so either or both may be specified.</simpara></note>
+ <simpara>
+ <computeroutput>maven -Dskip.jira.templates.data=true scarab:create-db</computeroutput>
+ </simpara>
+ <note>
+ <simpara>This option is independent of 'skip.seed.data', so either or both may be specified.</simpara>
+ </note>
</sect3>
</sect2>
<sect2>
@@ -351,7 +548,8 @@
<title>Step 6: [OPTIONAL] Run the tests</title>
<simpara>If you launch the tests now they will run on your recently configured database. Just do:</simpara>
<simpara> maven test</simpara>
- <simpara>The results of the tests will be in <computeroutput>$(SCARAB_HOME)/target/test-results/</computeroutput></simpara>
+ <simpara>The results of the tests will be in <computeroutput>$(SCARAB_HOME)/target/test-results/</computeroutput>
+ </simpara>
<simpara>If you'd like to make your tests with other db environment, follow these steps:</simpara>
<orderedlist>
<listitem>
Modified: trunk/www/book/install-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/install-fr.xml?view=diff&rev=10202&p1=trunk/www/book/install-fr.xml&p2=trunk/www/book/install-fr.xml&r1=10201&r2=10202
==============================================================================
--- trunk/www/book/install-fr.xml (original)
+++ trunk/www/book/install-fr.xml 2006-07-06 08:49:50-0700
@@ -128,94 +128,279 @@
</sect3>
<sect3>
<title>Télécharger Scarab et préparer son installation</title>
- <para>Il vous faut bien sûr finalement télécharger Scarab lui-même. Vous trouverez la dernière version (1.0-b16) à cette adresse: <ulink url="http://scarab.tigris.org/servlets/ProjectDocumentList">http://scarab.tigris.org/servlets/ProjectDocumentList</ulink>.</para>
+ <para>Il vous faut bien sûr finalement télécharger Scarab lui-même. Vous trouverez la dernière version (1.0-b21) à cette adresse: <ulink url="http://scarab.tigris.org/servlets/ProjectDocumentList">http://scarab.tigris.org/servlets/ProjectDocumentList</ulink>.</para>
<para>Décomprimez l'archive de Scarab dans le répertoire que vous choisirez.</para>
<para>L'essentiel de votre travail lors de l'installation portera dans un premier temps sur le répertoire ./build.</para>
</sect3>
</sect2>
</sect1>
<sect1>
- <title>Installer le système de gestion de base de données et préparer l'installation de Scarab</title>
+ <title>Installer et configurer MySQL</title>
<sect2>
- <title>MySQL</title>
+ <title>Guide pour les distributions linux utilisant des RPM</title>
<sect3>
- <title>Installer le SGBD</title>
- <para>Pour l'installation proprement dite, référez-vous aux instructions d'installation fournies avec le logiciel.</para>
+ <title>Récupérer une distribution de MySQL</title>
+ <simpara>Vous trouverez une distribution appropriée sur le <ulink url="|http://www.mysql.com">site web de MySQL</ulink>.</simpara>
+ <simpara>Suivez les instructions de la documentation de MySQL. On ne donnera ici que des informations résumées.</simpara>
+ </sect3>
+ <sect3>
+ <title>Installer la distribution</title>
+ <simpara>Si, par exemple, vous avez téléchargé la version 4.0.22, vous pouvez installer MySQL comme suit :</simpara>
+ <informalexample>
+ <programlisting>
+ rpm -i MySQL-server-4.0.22-0.i386.rpm MySQL-shared-4.0.22-0.i386.rpm MySQL-client-4.0.22-0.i386.rpm
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Initialiser et paramétrer votre serveur de base de données</title>
+ <simpara>Installez la base de données root d'abord et démarrez le démon mysql. Il semble que cette étape ne soit pas absolument requise, parce que l'installation des rpm's le fait déjà . Mais juste au cas où elle ne l'aurait pas fait, vous pouvez procéder manuellement :</simpara>
+ <informalexample>
+ <programlisting>
+mysql_install_db
+safe_mysqld
+ </programlisting>
+ </informalexample>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Configurer MySQL pour Scarab</title>
+ <simpara>La recette suivante détaille une manière d'éviter soigneusement les problèmes de connexion entre MySQL et Scarab, problèmes qui s'avèrent presque toujours relever de privilèges mal configurés. Supposons que vous avez une installation toute propre de MySQL sur votre système et que vous voulez exécuter MySQL et Scarab sur la même machine, à savoir <computeroutput>localhost</computeroutput>. Chaque étape est expliquée jusqu'à un certain niveau de détail. Il est possible que toutes les étapes ne soient pas nécessaires dans votre environnement.</simpara>
+ <sect3>
+ <title>Étape I (unix seulement) - Vérifier le fichier /etc/hosts</title>
+ <simpara>Si vous prévoyez d'exécuter MySQL sur localhost, vous devez vérifier l'entrée correspondante dans votre fichier /etc/hosts. Nous avons trouvé des problèmes lorsque l'entrée localhost est définie comme dans les exemples suivants :</simpara>
+ <informalexample>
+ <programlisting>
+127.0.0.1 localhost.localdomain localhost (vu sur Debian)
+127.0.0.1 linux localhost (vu sur Suse)
+ </programlisting>
+ </informalexample>
+ <simpara>Si vous trouvez ce genre d'entrée, inversez l'ordre de sorte que "localhost" apparaisse en premier :</simpara>
+ <informalexample>
+ <programlisting>
+127.0.0.1 localhost localhost.localdomain (sur Debian)
+127.0.0.1 localhost linux (sur Suse)
+ </programlisting>
+ </informalexample>
+ <simpara>Il se peut que vous ayiez à redémarrer la machine (mais ce n'est pas certain). Après le redémarrage, assurez-vous que le système d'exploitation n'a pas manipulé l'entrée de votre fichier /etc/hosts. Nous n'avons pas d'idée à vous suggérer si c'était le cas (mais si vous en aviez une, nous serions heureux de la connaître !).</simpara>
+ </sect3>
+ <sect3>
+ <title>Étape II - S'assurer que MySQL fonctionne correctement</title>
+ <simpara>Supposons que vous venez d'installer une instance de MySQL. MySQL est fourni avec un administrateur nommé "root", pour lequel il n'y a pas de mot de passe associé. Oui, c'est un gros problème de sécurité. Mais cela aide à démarrer sur MySQL rapidement. Nous reviendrons sur la sécurité à l'étape suivante.</simpara>
+ <simpara>Pour l'instant, essayez juste de lancer l'administration de la base. Vous pouvez faire cela en ligne de commande :</simpara>
+ <simpara>
+ <computeroutput>mysql -u root mysql</computeroutput>
+ </simpara>
+ <simpara>Vous devez maintenant avoir accès à la base de données d'administration de votre instance de MySQL. Si votre demande de connexion est rejetée, quelque chose d'inattendu a dû se produire. Soit votre base de données est corrompue, soit quelqu'un d'autre a installé la base et a paramétré la sécurité. Dans ce cas, vous devrez peut-être demander à votre administrateur de vous donner accès à la base de données "mysql" pour pouvoir passer à l'étape suivante.</simpara>
+ </sect3>
+ <sect3>
+ <title>Étape III - Sécuriser votre instance de MySQL (optionnel) (optional)</title>
+ <simpara>Une fois que vous êtes connecté(e) à la base de données, soit en tant que root, soit en tant qu'un administrateur (selon votre site), vous pouvez vérifier les droits :</simpara>
+ <informalexample>
+ <programlisting>
+select host, user, password from user;
+
+ +-----------+------+----------+
+ | host | user | password |
+ +-----------+------+----------+
+ | localhost | root | |
+ +-----------+------+----------+
+ 1 row in set (0.01 sec)
+ </programlisting>
+ </informalexample>
+ <simpara>Sécurisons maintenant l'instance. D'abord, nous voulons sécuriser l'utilisateur root. Nous lui donnons donc un mot de passe, ici "secret".</simpara>
+ <note>
+ <simpara>Cette étape n'est PAS nécessaire pour faire fonctionner Scarab; si vous ne souhaitez pas sécuriser votre base de données maintenant, n'exécutez pas l'instruction suivante.</simpara>
+ </note>
+ <informalexample>
+ <programlisting>
+grant all on *.* to root@localhost identified by 'secret';
+ </programlisting>
+ </informalexample>
+ <simpara>A partir de maintenant et pour toujours vous DEVEZ vous rappeler ce mot de passe! Voici à quoi ressemble maintenant la table user:</simpara>
+ <informalexample>
+ <programlisting>
+select host, user, password from user;
++-----------+------+-------------------------------------------+
+| host | user | password |
++-----------+------+-------------------------------------------+
+| localhost | root | *14E65567ABDB5135D0CFD9A70B3032C179A49EE7 |
++-----------+------+-------------------------------------------+
+1 row in set (0.00 sec)
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Étape IV - Ajouter l'utilisateur administrateur de Scarab</title>
+ <simpara>Nous choisissons <emphasis>admin</emphasis> comme administrateur avec le mot de passe <emphasis>secret</emphasis> et nous prenons <emphasis>scarab</emphasis> comme nom de base de données. Mais vous pouvez bien sûr en choisir d'autres.</simpara>
+ <note>
+ <simpara>Vous aurez besoin plus tard de TOUS les noms et identifiants choisis ci-dessus car ils devront figurer dans le fichier build.properties de Scarab !</simpara>
+ </note>
+ <informalexample>
+ <programlisting>
+ grant all on scarab.* to admin@localhost identified by 'secret';
+ grant grant option on scarab.* to admin@localhost;
+ grant all on mysql.* to admin@localhost;
+ </programlisting>
+ </informalexample>
+ <note>
+ <simpara>La seconde instruction est nécessaire parce que l'administrateur devra créer l'utilisateur associé à Scarab à l'exécution (voir plus bas) ! Le terme <computeroutput>grant grant option</computeroutput> ci-dessus est intentionnel, ce n'est pas une coquille ! La troisième instruction est nécessaire parce que l'utilisateur de la base scarab utilise un mot de passe pour s'identifier. Pour pouvoir définir les paramètres correspondants, l'administrateur doit avoir accès aux tables de contrôle contenues dans la base mysql.</simpara>
+ </note>
+ <simpara>Voici à quoi ressemble la table user maintenant:</simpara>
+ <informalexample>
+ <programlisting>
+select host, user, password from user;
++-----------+--------+-------------------------------------------+
+| host | user | password |
++-----------+--------+-------------------------------------------+
+| localhost | root | *14E65567ABDB5135D0CFD9A70B3032C179A49EE7 |
+| localhost | admin | *14E65567ABDB5135D0CFD9A70B3032C179A49EE7 |
++-----------+--------+-------------------------------------------+
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Étape V - Tester le paramétrage</title>
+ <caution>
+ <simpara>Par sécurité, gardez le shell courant ouvert et NE QUITTEZ PAS la session mysql. Ça peut aider si quelque chose se passe mal ;-)</simpara>
+ </caution>
+ <simpara>OK, ouvrez maintenant un nouveau shell et essayez de créer une base de données à partir de l'utilisateur admin:</simpara>
+ <informalexample>
+ <programlisting>
+mysqladmin -u admin -h localhost -p create scarab
+Enter password: ******
+ </programlisting>
+ </informalexample>
+ <simpara>Vous avez maintenant créé votre base de données scarab, même si elle est vide pour l'instant. Si la base de données était déjà présente, vous auriez reçu un message d'erreur approprié. Dans ce cas, ne continuez pas le processys sans avoir vérifié d'où vient cette base !</simpara>
+ <note>
+ <simpara>Cette étape n'est PAS requise par le paramétrage de Scarab mais procéder ainsi permet de s'assurer que les privilèges définis pour l'administrateur de Scarab sont corrects et fonctionnent comme prévu.</simpara>
+ </note>
+ </sect3>
+ <sect3>
+ <title>Étape VI - Configurer scarab
+ </title>
+ <simpara>Copiez le fichier minimal.properties (ou build.properties) et nommez la copie build.properties. Vous devez maintenant définir un utilisateur de base de données pour votre instance. Prenons par exemple "scarab" comme nom d'utilisateur MySQL et "baracs" comme mot de passe. Ces deux propriétés sont utilisées maintenant en plus de celles de l'utilisateur d'administration définies à l'étape IV ci-dessus (gardez tout cela à l'esprit quelques instants).</simpara>
+ <simpara>Éditez maintenant build.properties. Pour les paramètres de la base de données, repérez les propriétés suivantes :</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.username=scarab #changed from **GENERATED**
+scarab.database.password=baracs #changed from **GENERATED**
+scarab.database.admin.username=admin #changed from **GENERATED**
+scarab.database.admin.password=secret #changed from **GENERATED**
+scarab.database.host=localhost #unchanged
+scarab.database.name=scarab #unchanged
+ </programlisting>
+ </informalexample>
+ <simpara>Juste pour être complets: il y a d'autres propriétés qui peuvent être utilisées mais d'habitude elles sont générées à partir des paramètres ci-dessus. Les deux seules propriétés auxquelles vous devriez faire attention sont :</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.type=mysql #unchanged
+scarab.database.port=**GENERATED** #unchanged
+ </programlisting>
+ </informalexample>
+ <simpara>La première vaut mysql par défaut et la seconde sera positionnée à 3306 (le port standard utilisé par MySQL pour accepter des connexions).</simpara>
+ <note>
+ <simpara>Les propriétés database.username et database.password seront utilisées plus loin dans le processus pour créer automatiquement un utilisateur de base de données 'scarab' authentifié par le mot de passe 'baracs'. Il n'est donc pas utile de vous embêter à créer et paramétrer vous mêmes d'autres utilisateurs que l'utilisateur admin.</simpara>
+ </note>
+ </sect3>
+ <sect3>
+ <title>Étape VII - Construire Scarab</title>
+ <simpara>Allez dans le répertoire build et lancez la commande ant.</simpara>
+ <informalexample>
+ <programlisting>
+ ant
+ ant create-db
+ </programlisting>
+ </informalexample>
+ <simpara>Ces deux commandes devraient s'exécuter sans erreur maintenant et vous devriez voir quelque chose comme ceci dans le shell :</simpara>
+ <informalexample>
+ <programlisting>
+ [echo]
+ [echo] _________R U N T I M E B U I L D ___.
+ [echo] / _____/ ____ _____ ____________ \_ |__
+ [echo] \_____ \_/ ___\\__ \\_ __ \__ \ | __ \
+ [echo] / \ \___ / __ \| | \// __ \| \_\ \
+ [echo] /_______ /\___ >____ /__| (____ /___ /
+ [echo] \/ \/ \/ \/ \/
+ [echo]
+ [echo] [1.0-b20-200605092134]
+ [echo]
+ [echo]
+ [echo] Running with following options:
+ [echo]
+ [echo] database name = scarab
+ [echo] database type = mysql
+ [echo] jdbc driver = org.gjt.mm.mysql.Driver
+ [echo] database url = jdbc:mysql://localhost:3306/scarab?
+ [echo] host = localhost
+ [echo] port = 3306
+ [echo] username = scarab
+ [echo] admin user = Administrator
+ [echo]
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Reconstruire Scarab après un problème</title>
+ <simpara>Tout le paramétrage a été copié à divers endroits à partir de l'environnement de build, et la configuration peut ne plus être valide. Pour résoudre ce problème, vous devez régénérér la configuration (pas les fichiers classe). Vous pouvez utiliser ant pour ce faire :</simpara>
+ <informalexample>
+ <programlisting>
+cd build
+ant create-custom-property-file
+ </programlisting>
+ </informalexample>
+ <simpara>Mais vraiment, la manière la plus sûre de procéder est encore de tout reconstruire :</simpara>
+ <informalexample>
+ <programlisting>
+ant clean
+ant
+ant create-db
+ </programlisting>
+ </informalexample>
</sect3>
<sect3>
- <title>Créer un utilisateur pour Scarab</title>
- <para>Vous ne pourrez (ou vous ne souhaiterez) probablement pas faire tourner Scarab avec la sécurité par défaut de MySQL (utilisateur root sans mot de passe sur la machine locale). </para>
- <para>Il vous faudra donc créer un utilisateur au sens MySQL et lui donner les droits correspondants. Supposons que vous souhaitiez créer un utilisateur dont le nom sera 'scarab' sur un serveur local et lui donner tous les droits sur une base de données qui s'appellera elle aussi 'scarab'; connectez-vous à l'interface d'administration (commande <computeroutput>mysql</computeroutput>) et exécutez la commande suivante :</para>
- <para>
- <computeroutput>grant all privileges on scarab.* to scarab@localhost;</computeroutput>
- </para>
- <para>
- <computeroutput>flush privileges;</computeroutput>
- </para>
- <para>Si vous voulez que l'utilisateur 'scarab' de MySQL doive s'authentifier par un mot de passe 'secret', la syntaxe devient </para>
- <para>
- <computeroutput>grant all privileges on scarab.* to scarab@localhost identified by 'secret';</computeroutput>
- </para>
- <para>
- <computeroutput>flush privileges;</computeroutput>
- </para>
- </sect3>
- <sect3>
- <title>Définir les paramètres du SGBD dans Scarab</title>
- <para>Utilisez un éditeur pour ouvrir en lecture seule (si possible) le fichier default.properties dans le répertoire build de votre installation de Scarab. Ne modifiez pas ce fichier.</para>
- <para>Utilisez votre éditeur pour créer dans le même répertoire un fichier build.properties. Tous les paramètres que vous définirez dans ce fichier auront la préséance sur ceux qui sont définis dans default.properties. Ceci vous permet
- de conserver des valeurs par défaut raisonnables pour la plupart des clés, tout en redéfinissant les paramètres que vous souhaitez (ou devez) personnaliser.</para>
+ <title>En cas de problème</title>
<sect4>
- <title>Définir le type de base de données</title>
- <para>Vous n'aurez pas besoin de redéfinir le paramètre scarab.database.type, car par défaut (comme vous pouvez le voir dans default.properties):</para>
- <para>scarab.database.type=mysql</para>
- </sect4>
- <sect4>
- <title>Définir l'utilisateur du SGBD</title>
- <para>Si vous avez fait une installation par défaut de MySQL, vous n'êtes peut-être pas obligé(e) de définir scarab.database.username</para>
- <para>Dans la plupart des cas cependant, vous aurez spécifié un utilisateur (au sens user de MySQL). Vous devrez alors définir scarab.database.username, par exemple:</para>
- <para>scarab.database.username=user</para>
- <para>Si cet utilisateur a besoin d'un mot de passe pour s'identifier, définissez la clé scarab.database.password, par exemple:</para>
- <para>scarab.database.password=secret</para>
+ <title>Si ça ne marche toujours pas...</title>
+ <simpara>Voici deux liens supplémentaires vers des ressources qui peuvent vous aider à résoudre les problèmes de permissions :</simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <ulink url="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Access_denied">La documentation MySQL</ulink>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <ulink url="http://sourceforge.net/docman/display_doc.php?docid=8968&group_id=15923">sourceforge</ulink>
+ </simpara>
+ </listitem>
+ </itemizedlist>
</sect4>
<sect4>
- <title>Définir le serveur de base de données</title>
- <para>Par défaut</para>
- <para>scarab.database.host=127.0.0.1</para>
- <para>Si le serveur de base de données n'est pas sur la même machine que le moteur de servlet qui sert Scarab, redéfinissez la clé scarab.database.host en spécifiant le nom réseau du serveur MySQL ou son adresse IP.</para>
- <para>Si vous êtes confronté(e) à des erreurs d'accès à la base en local (access denied), vous devriez tenter éventuellement de remplacer 127.0.0.1 par localhost.</para>
+ <title>En dernier recours (s'applique à certaines distributions linux)</title>
+ <para>
+ Si ça ne marche toujours pas, vérifiez encore ceci
+ <footnote>
+ <simpara>Merci à Josh Howe pour sa contribution.</simpara>
+ </footnote>
+ . Le connecteur MySQL Connector/J ne peut communiquer avec MySQL qu'en utilisant
+ TCP/IP, puisque Java ne supporte pas les Unix domain sockets. La communication
+ TCP/IP avec MySQL peut être affectée si MySQL a été démarré avec l'option
+ --skip-networking ou s'il y a un firewall.
+ </para>
+ <para>
+ Si MySQL est démarré avec l'option --skip-networking (le package Linux Debian, par
+ exemple, procède ainsi), il vous faudra mettre en commentaire cette option dans le
+ fichier /etc/mysql/my.cnf ou /etc/my.cnf. Le fichier my.cnf peut aussi se trouver dans
+ le répertoire data de votre serveur MySQL ou n'importe où ailleurs (cela dépend
+ de la manière dont MySQL a été compilé pour votre système). Les binaires créés par
+ MySQL AB cherchent toujours ce fichier dans /etc/my.cnf et [datadir]/my.cnf.
+ Si votre serveur MySQL est derrière un firewall, vous devrez aussi penser à configurer
+ le firewall pour permettre les connexions TCP/IP depuis la machine qui héberge Scarab
+ jusqu'au serveur MySQL sur le port sur lequel MySQL écoute (par défaut, 3306).
+ </para>
</sect4>
</sect3>
- <sect3>
- <title>Télécharger un driver optimisé (option)</title>
- <para>Si vous faites une installation Scarab "de production", vous pouvez choisir d'utiliser un driver MySQL plus récent et plus performant que celui fourni avec Scarab (ce driver ne peut être fourni avec Scarab car sa licence est GPL).</para>
- <para>Téléchargez ce driver sur le site de MySQL à l'URL suivante: <ulink url="http://www.mysql.com/downloads/api-jdbc-dev.html">http://www.mysql.com/downloads/api-jdbc-dev.html</ulink>
- et copiez-le dans le répertoire lib de votre installation de Scarab.</para>
- <para>Vous devez aussi déclarer l'utilisation de ce nouveau driver dans votre fichier build.properties:</para>
- <para>scarab.database.jdbc.driver.jar=mysql-connector*.jar</para>
- </sect3>
- </sect2>
- <sect2>
- <title>PostgreSQL</title>
- <sect3>
- <title>Installer le SGBD</title>
- <para>Référez-vous aux instructions d'installation fournies avec le logiciel.</para>
- </sect3>
- <sect3>
- <title>Définir les paramètres du SGBD dans Scarab</title>
- <para/>
- </sect3>
- </sect2>
- <sect2>
- <title>Oracle 9i</title>
- <sect3>
- <title>Installer le SGBD</title>
- <para>Référez-vous aux instructions d'installation fournies avec le logiciel.</para>
- </sect3>
- <sect3>
- <title>Définir les paramètres du SGBD dans Scarab</title>
- <para/>
- </sect3>
</sect2>
</sect1>
<sect1>