Scarab commit: svn commit: r10256 - branches/release/b21: . www www/book www/book/images xdocs/databases
[email protected] 7 Aug 2006 22:38:00 -0000
Newsgroups
gmane.comp.java.scarab.cvs
Message-ID
<[email protected] >
Author: jorgeuriarte
Date: 2006-08-07 15:38:00-0700
New Revision: 10256
Added:
branches/release/b21/www/book/images/maven-scarab1.png
- copied unchanged from r10238, /trunk/www/book/images/maven-scarab1.png
branches/release/b21/www/book/images/maven-scarab2.png
- copied unchanged from r10238, /trunk/www/book/images/maven-scarab2.png
branches/release/b21/www/book/images/module-creation0.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation0.fr.png
branches/release/b21/www/book/images/module-creation0.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation0.png
branches/release/b21/www/book/images/module-creation1a.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation1a.fr.png
branches/release/b21/www/book/images/module-creation1a.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation1a.png
branches/release/b21/www/book/images/module-creation1b.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation1b.fr.png
branches/release/b21/www/book/images/module-creation1b.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation1b.png
branches/release/b21/www/book/images/module-creation2.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation2.fr.png
branches/release/b21/www/book/images/module-creation2.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation2.png
branches/release/b21/www/book/images/module-creation3.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation3.fr.png
branches/release/b21/www/book/images/module-creation3.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation3.png
branches/release/b21/www/book/images/module-creation4.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation4.fr.png
branches/release/b21/www/book/images/module-creation4.png
- copied unchanged from r10238, /trunk/www/book/images/module-creation4.png
branches/release/b21/www/book/images/module-edition1.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-edition1.fr.png
branches/release/b21/www/book/images/module-edition1.png
- copied unchanged from r10238, /trunk/www/book/images/module-edition1.png
branches/release/b21/www/book/images/module-edition2.fr.png
- copied unchanged from r10238, /trunk/www/book/images/module-edition2.fr.png
branches/release/b21/www/book/images/module-edition2.png
- copied unchanged from r10238, /trunk/www/book/images/module-edition2.png
branches/release/b21/www/book/images/pacs1-rss1.fr.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss1.fr.png
branches/release/b21/www/book/images/pacs1-rss2.fr.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss2.fr.png
branches/release/b21/www/book/images/pacs1-rss3.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss3.png
branches/release/b21/www/book/images/pacs1-rss4.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss4.png
branches/release/b21/www/book/images/pacs1-rss5.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss5.png
branches/release/b21/www/book/images/pacs1-rss6.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss6.png
branches/release/b21/www/book/images/pacs1-rss7.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss7.png
branches/release/b21/www/book/images/pacs1-rss8.png
- copied unchanged from r10238, /trunk/www/book/images/pacs1-rss8.png
branches/release/b21/www/book/integration-en.xml
- copied unchanged from r10238, /trunk/www/book/integration-en.xml
branches/release/b21/www/book/integration-fr.xml
- copied unchanged from r10238, /trunk/www/book/integration-fr.xml
Removed:
branches/release/b21/www/book/ide-en.xml
branches/release/b21/www/book/ide-fr.xml
Modified:
branches/release/b21/ (props changed)
branches/release/b21/www/book/install-en.xml
branches/release/b21/www/book/install-fr.xml
branches/release/b21/www/book/maven-en.xml
branches/release/b21/www/book/maven-fr.xml
branches/release/b21/www/book/modules-en.xml
branches/release/b21/www/book/modules-fr.xml
branches/release/b21/www/book/scarab-admin-en.xml
branches/release/b21/www/book/scarab-admin-fr.xml
branches/release/b21/www/book/scarab-user-de.xml
branches/release/b21/www/book/scarab-user-en.xml
branches/release/b21/www/book/scarab-user-fr.xml
branches/release/b21/www/users.html
branches/release/b21/xdocs/databases/index.xml
Log:
Integrated recent changes from trunk into release/b21 branch (via svnmerge)
Removed: branches/release/b21/www/book/ide-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/ide-en.xml?view=auto&rev=10255
Removed: branches/release/b21/www/book/ide-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/ide-fr.xml?view=auto&rev=10255
Modified: branches/release/b21/www/book/install-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/install-en.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/install-en.xml&p2=branches/release/b21/www/book/install-en.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/install-en.xml (original)
+++ branches/release/b21/www/book/install-en.xml 2006-08-07 15:38:00-0700
@@ -1,10 +1,6 @@
<!-- $Id$ -->
<chapter>
<title>Scarab Installation</title>
- <warning>
- <simpara>Information in this chapter dates back to milestone 17. You may find useful general information to choose, install or configure your database server but the information on building Scarab is outdated.</simpara>
- <simpara>Until this chapter is rewritten, always refer to the <computeroutput>INSTALL</computeroutput> file at the root of your Scarab installation directory.</simpara>
- </warning>
<sect1>
<title>General</title>
<sect2>
@@ -74,38 +70,30 @@
<para>The compatibility of Scarab with Oracle 9i has also been tested</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>
- <!-- Need to write a section here about DB2 -->
</sect3>
<sect3>
- <title>DBMS that have been tested and are not fully supported by Scarab</title>
- <sect4>
- <title>Microsoft SQL Server</title>
- <para>The Scarab configuration on Microsoft SQL Server has been carefully defined and tested.</para>
- <para>A few problems remain, related to the mapping of certain data types by Torque and to the use of the SQL CONCAT function. These problems have not been solved at the moment.</para>
- <para>People interested in the technical details on this question may refer to the appropriate documentation page on the Scarab web site.</para>
- </sect4>
- <sect4>
- <title>Hypersonic SQL</title>
- <para>Scarab has been configured and tested carefully on HyperSonic.</para>
- <para>However, the tests have shown that Scarab is not fully operational on this platform.</para>
- <para>People interested in the technical details on this question may refer to the appropriate documentation page on the Scarab web site.</para>
- </sect4>
- </sect3>
- <sect3>
- <title>DBMS that are not supported by Scarab</title>
- <sect4>
- <title>Oracle 8i</title>
- <para>Oracle 8i has been supported with some success at the beginning of the Scarab development.</para>
- <para>This support has been discontinued in 2003 due to compatibility problems in the syntax of some SQL joins. Unless someone tackles this problem, Oracle 8i will not be supported again.</para>
- <para>But Scarab is now compatible with Oracle 9i, as it has been discussed before.</para>
- </sect4>
+ <title>DBMS that have been tested and are not (fully) supported by Scarab</title>
+ <simpara>The following DBMS have their setup ready in Scarab and have been tested, but the tests have shown so far that Scarab is not fully operational on these platforms:</simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>Microsoft SQL Server<footnote><simpara>Problems remain with the use of the SQL CONCAT function and in the mapping of certain types by Torque.</simpara></footnote></simpara>
+ </listitem>
+ <listitem><simpara>HSQLDB</simpara></listitem>
+ <listitem><simpara>DB2</simpara></listitem>
+ </itemizedlist>
+ <simpara>Moreover:</simpara>
+ <itemizedlist>
+ <listitem><simpara>Apache Derby has been quickly tested recently; though it does not work at the moment, further testing is planned.</simpara></listitem>
+ <listitem><simpara>Oracle 8i has been supported in the early versions of Scarab but is no longer supported (and will not be supported again)<footnote><simpara>Unless someone volunteers but it is a tough problem with <emphasis>right outer joins</emphasis>.</simpara></footnote>.</simpara></listitem>
+ </itemizedlist>
</sect3>
</sect2>
<sect2>
<title>Choosing a servlet container</title>
- <para>Scarab runs on any Servlet 2.3-compatible servlet engine; in fact, a patch could make Scarab compatible with 2.2 servlet engines, among which WebSphere Application Server 4.0.</para>
- <para>Practically, most Scarab users use it on Tomcat; in fact, the Scarab installation process builds a "light" Tomcat server, the "sandbox", which you can use to test or run Scarab once it has been built.</para>
+ <para>Scarab runs on any Servlet 2.3-compatible servlet engine; in fact, a patch could make Scarab compatible with 2.2 servlet engines, among which WebSphere Application Server 4.0 -- but this has not been tested for a very long time.</para>
+ <para>Practically, most Scarab users use it on Tomcat; in fact, the Scarab installation process builds a "light" Tomcat server, the "sandbox", which you can use to test or run Scarab once it has been built.</para>
<para>You may want to deploy Scarab on an existing Tomcat installation; Resin has also been successfully tested as Scarab engine.</para>
+ <para>Deploying Scarab on "full" J2EE application servers has usually been tricky and has rarely worked. Recent tests have shown at least that it does not work "out of the box" neither on JBoss<footnote><simpara>Most probably there is at least a problem with the log4j settings.</simpara></footnote> nor on WebLogic Server.</para>
</sect2>
<sect2>
<title>Gathering the other elements required for the Scarab installation</title>
@@ -123,92 +111,482 @@
<para>You can download Ant from <ulink url="http://ant.apache.org">http://ant.apache.org</ulink>.</para>
<para>The Ant version should be 1.5.1 or greater.</para>
<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>
- </sect3>
- </sect2>
- </sect1>
- <sect1>
- <title>Installing the database software and preparing for Scarab installation</title>
- <sect2>
- <title>MySQL</title>
- <sect3>
- <title>Installing MySQL</title>
- <para>Please refer to the MySQL installation instructions.</para>
- </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>
- </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>
+ <caution>
+ <simpara>The version of ant that is supplied by RedHat with RHEL3 (latest update is ant-1.5.2-23) throws an exception when running the create-db target.</simpara>
+ <simpara>The exception is:</simpara>
+ <simpara>
+ <computeroutput>BUILD FAILED file:/export/home/admin/scarab/target/scarab/WEB-INF/conf/runtime-torque.xml:72: taskdef class org.apache.torque.task.TorqueDocumentationTask cannot be found</computeroutput>
+ </simpara>
+ <simpara>Work Around: use the version of ant that comes bundled with SCARAB:</simpara>
+ <itemizedlist>
+ <listitem><simpara>Copy it from <computeroutput>$SCARAB_ROOT/www/repository/ant/jars/ant-1.5.3-1.jar</computeroutput> to <computeroutput>$SCARAB_ROOT}/build</computeroutput></simpara></listitem>
+ <listitem><simpara>From $SCARAB_ROOT/build run <computeroutput>java âjar ant-1.5.3-1.jar create-db</computeroutput></simpara></listitem>
+ </itemizedlist>
+ </caution>
+ </sect3>
+ <sect3>
+ <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>
<sect2>
- <title>PostgreSQL</title>
- <sect3>
- <title>Installing PostgreSQL</title>
- <para>Please refer to the PostgreSQL installation instructions.</para>
- </sect3>
- <sect3>
- <title>Setting up the PostgreSQL in Scarab</title>
- <para/>
- </sect3>
+ <title>Understanding and setting up NTLM authentication</title>
+ <abstract>
+ <simpara>NTLM authentication provides automatic login (Single Sign-On) in Windows NT domains. It is only useful in carefully controlled and administered environments, it requires some additional setup, so if you don't plan to use this feature, you may (you should) skip this section.</simpara>
+ </abstract>
+ <sect3>
+ <title>Understanding NTLM authentication in Scarab</title>
+ <simpara>
+ This development is intended to provide the means for automatic login on
+ Windows networks. Initially based on code provided by Peter Nei (thanks!),
+ current implementation is mostly based on JCIFS (see note at the end of this doc).
+ </simpara>
+ <simpara>
+ It's implemented as a new valve in the pipeline (NtlmLoginValve), that
+ will try to get the credentials from the browser using the ntlm challenge
+ protocol.
+ </simpara>
+ <simpara>The credentials sent by the browser are not trusted directly, and they're authenticated in a NTLM domain.</simpara>
+ <simpara>
+ Given that feature is not automatically cross-browser (it needs some config tweaks in Firefox, and it's not
+ guaranteed to work on every browser), it might only makes sense in controlled network environments.
+ </simpara>
+ <sect4>
+ <title>Behaviour</title>
+ <simpara>The NTLM login will be inactive by default, and it will be activated using two Scarab properties:</simpara>
+ <simpara><computeroutput>scarab.login.ntlm.active=true|false</computeroutput></simpara>
+ <simpara>The setting of this property to <computeroutput>true</computeroutput> will require the authentication domain to be defined.</simpara>
+ <simpara><computeroutput>scarab.login.ntlm.domain=mydomaincontroller</computeroutput></simpara>
+ <simpara>
+ When browsing, the NTLMLoginValve will try to get the credentials and
+ validate them against the NTLM domain.
+ If they are valid. it will try logging in the user into Scarab.
+ <emphasis role="bold">For this to succeed, the NTLM usename must match an Scarab username.</emphasis>
+ If the user gets logged in, a message will be displayed, such as</simpara>
+ <informalexample>
+ <programlisting>
+ You've been automatically logged in using your user 'YourUser' from domain 'YourDomain'."
+ </programlisting>
+ </informalexample>
+ <simpara>
+ If anyone from the NTLM credentials or its equivalent Scarab username are invalid, the valve will
+ just 'pass' and the rest of the login system will proceed (Login form / Anonymous).
+ </simpara>
+ <simpara>
+ When an authenticated user (even Anonymous) click on the 'Logout/Login' link, the session will be
+ terminated and the Login.vm screen will be displayed, so any user (NTLM or
+ not) can try logging in the system with other credentials.
+ </simpara>
+ </sect4>
+ <sect4>
+ <title>Single-Sign-On behaviour</title>
+ <simpara>
+ User are still able to login using the old form, and this causes a
+ problem because Scarab and NTLM passwords will not be synchronized.
+ </simpara>
+ <simpara>Possible solutions:</simpara>
+ <orderedlist>
+ <listitem>
+ <simpara>Disable form-login: This would be a problem if some users are not to be in the Windows domain.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Use a UserPreference to choose between NTLM and form login for every user. This would effectively restrict
+ any user to only one authentication method, be Scarab or NTLM, but it would add another administration task.
+ password in Scarab, the NTLM PASSWORD WILL NOT CHANGE, and neither .
+ Similarly, the Windows domain can revoke or
+ </simpara>
+ </listitem>
+ </orderedlist>
+ </sect4>
+ <sect4>
+ <title>Login precedences</title>
+ <simpara>The different login methods allowed will be selected in this order:</simpara>
+ <orderedlist>
+ <listitem><simpara>Login form will always take precedence on others.</simpara></listitem>
+ <listitem><simpara>If the login-form has not been used, the system will try NTLM authentication (if activated!)</simpara></listitem>
+ <listitem><simpara>Anonymous login will be granted if allowed.</simpara></listitem>
+ </orderedlist>
+ </sect4>
+ <sect4>
+ <title>Firefox</title>
+ <simpara>
+ Firefox users will be by default prompted with a dialog box asking for
+ username and password. To login with Windows domain credentials, the user will have to fill them up using the DOMAIN\User format.
+ </simpara>
+ <simpara>Example: Username: "MyDomain\mywindowsuser", Password: myplainpassword</simpara>
+ <simpara>
+ If Firefox users want to automatically (no dialog!) get the credentials fed from the underlaying Windows
+ operating system, they have to:</simpara>
+ <itemizedlist>
+ <listitem><simpara>Type "about:config" in the URL box.</simpara></listitem>
+ <listitem><simpara>Search for the 'network.automatic-ntlm-auth.trusted-uris' configuration value.</simpara></listitem>
+ <listitem><simpara>Add the name of the Scarab host to that value.</simpara></listitem>
+ </itemizedlist>
+ </sect4>
+ <sect4>
+ <title>Other browsers</title>
+ <simpara>The feature has not been tested on other browsers. At least, they would probably offer the dialog asking for username and password, but it may vary.</simpara>
+ </sect4>
+ </sect3>
+ <sect3>
+ <title>Preparing Scarab for NTLM authentication</title>
+ <abstract><simpara>You have to perform some library setup before building Scarab; that is why this lengthy thread about NTLM authentication took place here.</simpara></abstract>
+ <sect4>
+ <title>jcifs</title>
+ <simpara>To perform NTLM authentication, Scarab relies on the jcifs library, part of the Samba project (<ulink url="http://jcifs.samba.org">http://jcifs.samba.org</ulink>).</simpara>
+ <simpara>The license of jcifs is LGPL, so the jar cannot be included in the Scarab distribution.</simpara>
+ <simpara>
+ Some Apache projects (Lenya) have been using jcifs, providing a <emphasis role="bold">mock jar</emphasis> to allow compiling and asking the administrator to manually download the (real) jar.
+ This method fits Scarab too, so you will have to download jcifs yourself from one of these URls:</simpara>
+ <itemizedlist>
+ <listitem><simpara><ulink url="http://jcifs.samba.org/">http://jcifs.samba.org/</ulink></simpara></listitem>
+ <listitem><simpara><ulink url="http://www.ibiblio.org/maven/org.samba.jcifs/jars/jcifs-1.2.6.jar">http://www.ibiblio.org/maven/org.samba.jcifs/jars/jcifs-1.2.6.jar</ulink></simpara></listitem>
+ </itemizedlist>
+ <simpara>
+ Once you have got the jar file, you must replace the jar that was delivered with Scarab.
+ Be aware that if you are using Maven, you have possibly already got the mock version in your local Maven repository (usually at $HOME/.maven/repository/org.samba.jcifs/jars).
+ </simpara>
+ <warning><simpara>You must replace the (mock) jar with the real jar you have downloaded.</simpara></warning>
+ </sect4>
+ </sect3>
</sect2>
- <sect2>
- <title>Oracle 9i</title>
- <sect3>
- <title>Installing Oracle 9i</title>
- <para>Please refer to the Oracle 9i installation instructions.</para>
- </sect3>
- <sect3>
- <title>Setting up the Oracle 9i parameters in Scarab</title>
- <para/>
- </sect3>
+ </sect1>
+ <sect1>
+ <title>Setting up and configuring your database for Scarab</title>
+ <sect2>
+ <title>Installing and configuring MySQL</title>
+ <sect3>
+ <title>Guide for Linux with RPM packages</title>
+ <sect4>
+ <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>
+ </sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ </sect3>
+ <sect3>
+ <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>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <title>Troubleshooting</title>
+ <sect5>
+ <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>
+ </sect5>
+ <sect5>
+ <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>
+ </sect5>
+ </sect4>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Configuring PostgreSQL</title>
+ <simpara>
+ Due to a problem in the database persistence framework we use, Scarab
+ will not work "out-of-the-box" with PostgreSQL. Fortunately, there is
+ a simple script that you can run which will create a work-around.
+ </simpara>
+ <simpara>
+ This script must be run by a user with sufficient privileges, which
+ generally means the user that originally created and initialised the
+ PostgreSQL database. Typically this user will be 'postgres'.
+ </simpara>
+ <simpara>
+ The script can be found at <computeroutput>src/sql/postgresql/hack-db.sql</computeroutput> in the
+ distribution, and it can be executed in different ways, for example
+ from the command line:
+ </simpara>
+ <informalexample>
+ <programlisting>postgres> psql scarab < hack-db.sql</programlisting>
+ </informalexample>
+ <simpara>
+ where 'scarab' is the name of the Scarab database, and 'postgres' is
+ the "system" postgreSQL user. Alternatively, from the psql interactive
+ console:
+ </simpara>
+ <informalexample>
+ <programlisting>scarab=> \i hack-db.sql</programlisting>
+ </informalexample>
+ </sect2>
+ <sect2>
+ <title>Setting up and configuring Oracle</title>
+ <sect3>
+ <title>Getting the JDBC drivers</title>
+ <simpara>For licence reasons, the jar containing the Oracle JDBC driver is not included in the Scarab distribution.</simpara>
+ <simpara>You will have to get it yourself from your Oracle distribution (or from Oracle Technology Network: <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html">http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html</ulink>). Unless you have a compelling reason to do otherwise, you should take the latest drivers: they are compatible with older releases of Oracle but are much faster than the older drivers.</simpara>
+ <simpara>The jar you need is probably named <computeroutput>classes12.jar</computeroutput> (for JDK 1.2 and 1.3) or <computeroutput>ojdbc14.jar</computeroutput> (for JDK 1.4 and 1.5). Copy this jar to the <computeroutput>$SCARAB/lib</computeroutput> directory (i.e., the lib directory directly at the root of your Scarab distribution. In a fresh installation of Scarab, this directory is probably empty, except for a README file. This is normal, it is populated during the build process.</simpara>
+ </sect3>
+ <sect3>
+ <title>Configuring access to your Oracle database</title>
+ <simpara>In the <computeroutput>build.properties</computeroutput> file you will prepare in Step 3 below, you will need to configure the access to your Oracle database.</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.host=localhost
+scarab.database.port=
+scarab.database.url=
+scarab.database.admin.url=
+scarab.database.type=oracle
+scarab.database.jdbc.driver=oracle.jdbc.driver.OracleDriver
+scarab.database.username=scarab
+scarab.database.password=secret
+scarab.database.admin.username=scott
+scarab.database.admin.password=tiger
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Solving a problem with LOBs</title>
+ <simpara>To use Large OBjects (LOBs), such as BLOBs (Binary Large OBjects) and CLOBs (Character Large OBjects) you need to instantiate Oracle classes (not JDBC generic classes) and the current version of the persistance layer we use, Torque, does not allow to do that at the moment. A workaround is to use large VARCHARs instead. To change this, you will need to patch the <computeroutput>webapps/scarab/WEB-INF/sql/turbine.sql</computeroutput> after building Scarab (see next section), replacing <computeroutput>BLOB</computeroutput> by <computeroutput>VARCHAR2(4000)</computeroutput><footnote><simpara>You can as well edit <computeroutput>webapps/scarab/WEB-INF/src/torque/templates/sql/base/oracle/db.props</computeroutput> and change <computeroutput>VARBINARY = BLOB</computeroutput> to <computeroutput>VARBINARY = VARCHAR2(4000)</computeroutput> -- that is a slightly more persistent modi
fication.</simpara></footnote></simpara>
+ </sect3>
+ <sect3>
+ <title>Using Oracle 10g XE on the same machine as Scarab</title>
+ <simpara>A word of caution if you plan to use Scarab on the same machine as Oracle 10g XE. Both Scarab and the Oracle administration web app listen by default on the same port (8080), which will cause a conflict.</simpara>
+ <simpara>To configure Scarab to listen on a different port, change the <computeroutput>scarab.http.port</computeroutput> property to a value you choose and edit the <computeroutput>./tomcat/conf.server.xml</computeroutput> file to configure Tomcat to listen to a different port.</simpara>
+ <simpara>To change the port on which the Oracle administration web app listens, consult the Oracle 10g XE documentation.</simpara>
+ </sect3>
</sect2>
</sect1>
<sect1>
@@ -251,8 +629,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>
@@ -265,44 +647,14 @@
</sect2>
<sect2>
<title>Step 4: Build Scarab</title>
- <para>You have two choices to build Scarab:</para>
- <orderedlist>
- <listitem>
- <simpara>Maven build:</simpara>
- <orderedlist>
- <listitem>
- <simpara>Enter the $SCARAB_ROOT directory</simpara>
- </listitem>
- <listitem>
- <simpara>call maven as follows:</simpara>
- <simpara>maven war -Dmaven.test.skip</simpara>
- <note>
- <simpara>
- <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!
- Given the tests are intended to work against a database,
- it's possible that you see them fail in this step if your
- database is not already configured. Look at the
- </simpara>
- </note>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <simpara>Ant build:</simpara>
- <orderedlist>
- <listitem>
- <simpara>Enter the $SCARAB_ROOT/build directory</simpara>
- </listitem>
- <listitem>
- <simpara>call ant as follows:</simpara>
- <simpara>ant</simpara>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
+ <simpara>Go to the <computeroutput>$SCARAB_ROOT/build</computeroutput> directory.</simpara>
+ <simpara>Launch ant::</simpara>
+ <simpara><computeroutput>ant</computeroutput></simpara>
+ <note>
+ <simpara>If you are a developer, particularly a Scarab developer, you may also build Scarab with Maven 1.</simpara>
+ <simpara>This will give you additional features and options, such as running unit tests.</simpara>
+ <simpara>For detailed information, see the chapter 3 in the Developer's Guide.</simpara>
+ </note>
</sect2>
<sect2>
<title>Step 5a: Create the database</title>
@@ -334,10 +686,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>
@@ -348,31 +706,7 @@
<simpara>Go to MIGRATION file for instructions on migrating your existing data.</simpara>
</sect2>
<sect2>
- <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>If you'd like to make your tests with other db environment, follow these steps:</simpara>
- <orderedlist>
- <listitem>
- <simpara>maven clean (you better start from scratch if you gonna test)</simpara>
- </listitem>
- <listitem>
- <simpara>Configure your build.properties to contain at least the correct scarab.database.type value.</simpara>
- </listitem>
- <listitem>
- <simpara>maven war</simpara>
- </listitem>
- <listitem>
- <simpara>maven scarab:create-db (make sure you choose the same database than before!!)</simpara>
- </listitem>
- <listitem>
- <simpara>maven test</simpara>
- </listitem>
- </orderedlist>
- </sect2>
- <sect2>
- <title>Step 7: Start Tomcat</title>
+ <title>Step 6: Start Tomcat</title>
<simpara>On Windows, double-click on the file $SCARAB_HOME/tomcat/bin/startup.bat</simpara>
<simpara>On Unix/Linux, run the following shell script: $SCARAB_HOME/tomcat/bin/startup.sh'</simpara>
<simpara>The webapplication will be available as reflected by the settings of the following properties (see step 3):</simpara>
Modified: branches/release/b21/www/book/install-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/install-fr.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/install-fr.xml&p2=branches/release/b21/www/book/install-fr.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/install-fr.xml (original)
+++ branches/release/b21/www/book/install-fr.xml 2006-08-07 15:38:00-0700
@@ -1,17 +1,13 @@
<!-- $Id$ -->
<chapter>
<title>Installer Scarab</title>
- <warning>
- <simpara>Les informations présentes dans ce chapitre datent de la version milestone 17. Vous pouvez trouver ici quelques informations utiles pour choisir, installer ou configurer votre base de données mais ce qui concerne la construction de Scarab lui-même est pour l'essentiel périmé.</simpara>
- <simpara>En attendant que ce chapitre soit réécrit, référez-vous toujours au fichier <computeroutput>INSTALL</computeroutput> présent dans le répertoire racine de votre installation Scarab.</simpara>
- </warning>
<sect1>
<title>Généralités</title>
<sect2>
<title>Comment installer Scarab</title>
- <para>En l'état actuel du développement -- et peut-être également dans le long terme -- Scarab s'installe pas tout assemblé, avec par exemple un programme d'installation.</para>
+ <para>En l'état actuel du développement -- et peut-être également dans le moyen terme -- Scarab ne s'installe pas tout assemblé, avec par exemple un programme d'installation.</para>
<para>Au lieu de cela, Scarab est construit dynamiquement pour chaque installation particulière, en fonction des paramètres locaux mais surtout du système de gestion de base de données utilisé pour stocker les fiches et les autres informations dont Scarab a besoin.</para>
- <para>Cette perspective peut vous inquiéter de prime abord, mais la procédure est simple et éprouvée: vous devriez donc y parvenir sans difficultés, comme bien d'autres avant vous.</para>
+ <para>Cette perspective peut vous inquiéter de prime abord mais la procédure est raisonnablement simple et bien éprouvée : vous devriez donc y parvenir sans difficultés, comme bien d'autres avant vous.</para>
</sect2>
<sect2>
<title>Le schéma d'une installation type</title>
@@ -47,7 +43,7 @@
<para>Windows</para>
</listitem>
<listitem>
- <para>MacOS X: Scarab est d'ailleurs partiellement développé dans cet environnement et le premier démonstrateur, la "runbox", a tourné pendant des mois sur cette plate-forme.</para>
+ <para>MacOS X: Scarab est d'ailleurs partiellement développé dans cet environnement et le premier démonstrateur, la "runbox", a tourné pendant des mois sur cette plate-forme.</para>
</listitem>
</itemizedlist>
</sect2>
@@ -75,48 +71,40 @@
<para>La compatibilité de Scarab avec Oracle 9i est testée.</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>
- <!-- Il faut écrire quelque chose ici à propos de DB2 -->
</sect3>
<sect3>
<title>SGBD testés et incomplètement supportés par Scarab</title>
- <sect4>
- <title>Microsoft SQL Server</title>
- <para>La configuration de Scarab sur Microsoft SQL Server a été définie et testée avec soin.</para>
- <para>Les derniers problèmes rencontrés, relatifs au mapping de certains types par Torque et à l'utilisation de la fonction SQL CONCAT n'ont pu être résolus pour l'instant.</para>
- <para>Ceux qui sont intéressés par les détails techniques se réfèreront utilement à la page ad hoc du site web de Scarab (en anglais).</para>
- </sect4>
- <sect4>
- <title>Hypersonic SQL</title>
- <para>Scarab a été configuré et testé avec soin sur Hypersonic.</para>
- <para>Ici non plus, les essais n'ont pu être menés jusqu'à une solution opérationnelle de façon satisfaisante.</para>
- <para>Ceux qui sont intéressés par les détails techniques se réfèreront utilement à la page ad hoc du site web de Scarab (en anglais).</para>
- </sect4>
- </sect3>
- <sect3>
- <title>SGBD testés et non supportés par Scarab</title>
- <sect4>
- <title>Oracle 8i</title>
- <para>Oracle 8i a été supporté avec plus ou moins de succès au début du développement de Scarab.</para>
- <para>Ce support a été interrompu en 2003 pour des raisons de compatibilité dans la syntaxe SQL de certaines jointures, et ne sera pas repris (sauf si quelqu'un trouve et fournit une solution satisfaisante à ce problème).</para>
- <para>Scarab est par contre maintenant compatible avec Oracle 9i.</para>
- </sect4>
+ <simpara>Les SGBD suivants peuvent être paramétrés dans Scarab mais les tests effectués montrent que Scarab n'est pas complètement opérationnel sur ces plate-formes :</simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>Microsoft SQL Server<footnote><simpara>Des problèmes subsistent au niveau de l'utilisation de la fonction SQL CONCAT et dans le mapping de certains types par Torque.</simpara></footnote></simpara>
+ </listitem>
+ <listitem><simpara>HSQLDB</simpara></listitem>
+ <listitem><simpara>DB2</simpara></listitem>
+ </itemizedlist>
+ <simpara>En outre :</simpara>
+ <itemizedlist>
+ <listitem><simpara>De premiers essais ont eu lieu récemment avec Apache Derby et ne sont pas concluants pour l'instant mais ils seront poursuivis.</simpara></listitem>
+ <listitem><simpara>Oracle 8i a été supporté dans les premières versions de Scarab mais n'est plus supporté et ne le sera probablement plus jamais<footnote><simpara>Il s'agit d'un problème relatif aux <emphasis>right outer joins</emphasis>.</simpara></footnote>.</simpara></listitem>
+ </itemizedlist>
</sect3>
</sect2>
<sect2>
<title>Choisir un moteur de servlet</title>
- <para>Scarab est en principe compatible avec tout moteur de servlet compatible avec la norme Servlet 2.3;
- un patch permet théoriquement de le rendre compatible avec des moteurs de servlet compatibles avec le standard 2.2, notamment WebSphere Application Server 4.0.</para>
+ <para>Scarab est en principe compatible avec tout moteur de servlet compatible avec la norme Servlet 2.3 ;
+ un patch permet théoriquement de le rendre compatible avec des moteurs de servlet compatibles avec le standard 2.2, notamment WebSphere Application Server 4.0 -- mais ceci n'a plus été testé depuis longtemps.</para>
<para>En pratique, la plupart des utilisateurs de Scarab le mettent en oeuvre avec un serveur Tomcat; d'ailleurs, le processus de construction de Scarab construit également un serveur Tomcat allégé, "the sandbox", que vous pouvez utiliser pour tester ou faire fonctionner Scarab dès qu'il est construit.</para>
<para>Vous pouvez également choisir de déployer Scarab derrière une installation existante de Tomcat; par ailleurs, des essais ont été également menés de manière satisfaisante sur Resin.</para>
+ <para>Le déploiement de Scarab sur des serveurs d'applications J2EE complets est assez délicat et rarement concluant; les essais menés sur JBoss<footnote><simpara>Sur JBoss il s'agit probablement d'un problème de paramétrage de log4j.</simpara></footnote> et sur WebLogic Server n'ont pas abouti pour l'instant.</para>
</sect2>
<sect2>
<title>Récupérer les autres éléments nécessaires à l'installation de Scarab</title>
<para>Pour procéder à l'installation de Scarab, vous aurez encore besoin de trois choses: un SDK Java, le système de construction Ant et bien sûr Scarab lui-même.</para>
<sect3>
- <title>Télécharger et installer un JDK Java</title>
+ <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>Vous pouvez télécharger un JDK à 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>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>
<sect3>
@@ -125,97 +113,485 @@
<para>Vous pouvez télécharger Ant à partir de <ulink url="http://ant.apache.org">http://ant.apache.org</ulink>.</para>
<para>La version peut être 1.4 ou 1.5 (si vous vouliez recompiler la version de Torque embarquée dans Scarab, vous devriez utiliser une version 1.4; cette manoeuvre est de toute façon réservée aux développeurs patentés).</para>
<para>Assurez-vous que la variable d'environnement ANT_HOME pointe sur le répertoire dans lequel Ant est installé.</para>
+ <caution>
+ <simpara>La version de ant fournie par RedHat avec RHEL3 (dont la dernière mise à jour est ant-1.5.2-23) lance une exception dans la cible create-db.</simpara>
+ <simpara>L'exception est la suivante :</simpara>
+ <simpara>
+ <computeroutput>BUILD FAILED file:/export/home/admin/scarab/target/scarab/WEB-INF/conf/runtime-torque.xml:72: taskdef class org.apache.torque.task.TorqueDocumentationTask cannot be found</computeroutput>
+ </simpara>
+ <simpara>Pour contourner ce problème, utilisez la version de ant fournie avec Scarab :</simpara>
+ <itemizedlist>
+ <listitem><simpara>Copiez l'archive de <computeroutput>$SCARAB_ROOT/www/repository/ant/jars/ant-1.5.3-1.jar</computeroutput> vers <computeroutput>$SCARAB_ROOT}/build</computeroutput></simpara></listitem>
+ <listitem><simpara>Dans le répertoire $SCARAB_ROOT/build lancez la commande <computeroutput>java âjar ant-1.5.3-1.jar create-db</computeroutput></simpara></listitem>
+ </itemizedlist>
+ </caution>
</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>
- <sect2>
- <title>MySQL</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>
- </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>
- <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>
- </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>
- </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>
+ <title>Comprendre et paramétrer l'authentification par NTLM</title>
+ <abstract>
+ <simpara>L'authentification par NTLM permet de se loguer automatiquement (Single-Sign On) dans un domaine Windows NT. C'est une fonctionnalité qui n'est utile que dans des environnements bien contrôlés et administrés ; si vous ne pensez pas l'utiliser, sautez sans hésiter cette section.</simpara>
+ </abstract>
+ <sect3>
+ <title>Comprendre l'authentification par NTLM dans Scarab</title>
+ <simpara>
+ Le développement de cette fonctionnalité a été entrepris pour permettre de se loguer automatiquement lorsqu'on travaille au sein d'un réseau Windows.
+ Elle est basée sur du code fourni par Peter Nei (merci à lui) mais l'implémentation actuelle est pour l'essentiel basée sur JCIFS (voir à la fin de cette section).
+ </simpara>
+ <simpara>
+ L'authentification NTLM est implémentée sous forme d'une nouvelle valve (<computeroutput>NtlmLoginValve</computeroutput>) dans le pipeline,
+ qui tente d'obtenir l'identification de l'utilisateur depuis le navigateur en utilisant le protocole de challenge NTLM.
+ </simpara>
+ <simpara>Les éléments d'identité renvoyés par le navigateur ne sont pas acceptés directement, ils sont authentifiés dans le domaine NTLM.</simpara>
+ <simpara>
+ Étant donné que cette fonctionnalité est spécifique à chaque navigateur (elle nécessite un peu de configuration dans Firefox, par exemple,
+ comme on verra plus loin) et qu'elle n'a pas été testée sur tous les navigateurs, cela n'a probablement de sens de l'utiliser que dans des environnements
+ réseau bien contrôlés.
+ </simpara>
+ <sect4>
+ <title>Comportement</title>
+ <simpara>Le login par NTLM est désactivé par défaut ; il est activé en définissant deux propriétés Scarab :</simpara>
+ <simpara><computeroutput>scarab.login.ntlm.active=true|false</computeroutput></simpara>
+ <simpara>Positionner cette propriété à <computeroutput>true</computeroutput> nécessite de spécifier le domaine d'authentification.</simpara>
+ <simpara><computeroutput>scarab.login.ntlm.domain=mydomaincontroller</computeroutput></simpara>
+ <simpara>
+ Lorsque l'utilisateur arrive dans Scarab, NTLMLoginValve va tenter d'obtenir ses éléments d'identification et va les valider dans le domaine NTLM.
+ S'ils sont valides, NTLMLoginValve va tenter de loguer l'utilisateur dans Scarab.
+ <emphasis role="bold">Pour que cela fonctionne, le nom d'utilisateur NTLM doit correspondre à un nom d'utilisateur Scarab.</emphasis>
+ Si l'utilisateur peut être logué, un message est affiché, comme</simpara>
+ <informalexample>
+ <programlisting>
+ You've been automatically logged in using your user 'YourUser' from domain 'YourDomain'."
+ </programlisting>
+ </informalexample>
+ <simpara>
+ Si les éléments d'identification fournis par NTLM ou le nom d'utilisateur Scarab correspondant ne sont pas valides,
+ la valve "passe son tour" et le reste du système d'identification normal de Scarab se déroule
+ (formulaire d'identification, login anonyme).
+ </simpara>
+ <simpara>
+ Lorsqu'un utilisateur authentifié (même Anonyme) clique sur le lien "Déconnexion", la session
+ est terminée et l'écran de Login (Login.vm) est affiché pour permettre à un autre utilisateur
+ (identifié par NTLM ou non) de tenter de se connecter au système avec d'autres identifiants.
+ </simpara>
+ </sect4>
+ <sect4>
+ <title>Single-Sign-On</title>
+ <simpara>
+ Un utilisateur peut toujours se connecter en utilisant le formulaire habituel ;
+ ceci pose problème parce que les mots de passe Scarab et NTLM peuvent
+ ne plus être synchronisés.
+ </simpara>
+ <simpara>Solutions possibles :</simpara>
+ <orderedlist>
+ <listitem>
+ <simpara>Désactiver le login au moyen du formulaire habituel. Ceci pose problème si certains utilisateurs n'appartiennent pas au domaine Windows.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Utiliser une préférence utilisateur (UserPreference) pour choisir entre login NTLM et login par formulaire pour chaque utilisateur.
+ Ceci restreint chaque utilisateur à un mode donné d'authentification, Scarab ou NTLM mais ajoute une tâche d'administration.
+ </simpara>
+ </listitem>
+ </orderedlist>
+ </sect4>
+ <sect4>
+ <title>Ordre de précédence</title>
+ <simpara>Les différentes méthodes de login possibles sont sélectionnées dans cet ordre :</simpara>
+ <orderedlist>
+ <listitem><simpara>L'identification utilisant la page de login de Scarab a priorité sur toutes les autres..</simpara></listitem>
+ <listitem><simpara>Si le formulaire de login n'a pas été utilisaé, le système essayera l'auhentification par NTLM (si elle est actifée, bien sûr).</simpara></listitem>
+ <listitem><simpara>Un login anonyme sera accordé si c'est permis.</simpara></listitem>
+ </orderedlist>
+ </sect4>
+ <sect4>
+ <title>Firefox</title>
+ <simpara>
+ Les utilisateurs de Firefox recevront par défaut une boîte de dialogue demandant un nom d'utilisateur et un mot de passe.
+ Pour se loguer avec les éléments d'identification du domaine Windows, l'utilisateur doit répondre en entrant les données
+ au format DOMAIN\User.
+ </simpara>
+ <simpara>Exemple: Username: "MyDomain\mywindowsuser", Password: myplainpassword</simpara>
+ <simpara>
+ Si les utilisateurs de Firefox veulent fournir les éléments d'identification du système d'exploitation
+ Windows, ils doivent :
+ </simpara>
+ <itemizedlist>
+ <listitem><simpara>Taper "about:config" dans la zone de saisie d'URL.</simpara></listitem>
+ <listitem><simpara>Rechercher la clé de configuration 'network.automatic-ntlm-auth.trusted-uris'.</simpara></listitem>
+ <listitem><simpara>Ajouter le nom du serveur Scarab à la valeur correspondante.</simpara></listitem>
+ </itemizedlist>
+ </sect4>
+ <sect4>
+ <title>Autres navigateurs</title>
+ <simpara>Cette fonctionnalité n'a pas été testée avec d'autres navigateurs. Les autres navigateurs présentent probablement à l'utilisateur une boîte de dialogue demandant un nom d'utilisateur et un mot de passe mais cela peut varier.</simpara>
+ </sect4>
+ </sect3>
+ <sect3>
+ <title>Préparer le build de Scarab avec l'authentification par NTLM</title>
+ <abstract><simpara>Il y a une petite manipulation à faire sur les bibliothèques (archives) avant de construire Scarab ; c'est pourquoi cette longue discussion sur l'authentification par NTLM a pris place ici.</simpara></abstract>
+ <sect4>
+ <title>jcifs</title>
+ <simpara>Pour implémenter l'authentification par NTLM, Scarab utilise la bibliothèque java jcifs, qui fait partie du projet Samba (<ulink url="http://jcifs.samba.org">http://jcifs.samba.org</ulink>).</simpara>
+ <simpara>La licence de jcifs est la LGPL, c'est pourquoi son jar ne peut pas être inclus dans la distribution de Scarab.</simpara>
+ <simpara>
+ Certains projets Apache (Lenya) utilisent déjà jcifs, en fournissant un <emphasis role="bold">jar factice</emphasis> pour permettre la compilation et en demandant à l'administrateur de télécharger lui-même le jar réel.
+ Cette méthode convient aussi pour Scarab, il vous faudra donc télécharger vous-même jcifs à l'une de ces adresses :</simpara>
+ <itemizedlist>
+ <listitem><simpara><ulink url="http://jcifs.samba.org/">http://jcifs.samba.org/</ulink></simpara></listitem>
+ <listitem><simpara><ulink url="http://www.ibiblio.org/maven/org.samba.jcifs/jars/jcifs-1.2.6.jar">http://www.ibiblio.org/maven/org.samba.jcifs/jars/jcifs-1.2.6.jar</ulink></simpara></listitem>
+ </itemizedlist>
+ <simpara>
+ Une fois que vous avez téléchargé le jar, vous devez remplacer le jar fourni avec Scarab.
+ Attention, si vous utilisez Maven, il est possible que vous ayez déjà la version factice dans votre repository Maven local (normalement sous <computeroutput>$HOME/.maven/repository/org.samba.jcifs/jars</computeroutput>).
+ </simpara>
+ <warning><simpara>Vous devez remplacer le jar factice par le jar réel que vous aurez téléchargé.</simpara></warning>
+ </sect4>
+ </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>
+ </sect1>
+ <sect1>
+ <title>Configurer votre base de données pour Scarab</title>
+ <sect2>
+ <title>Installer et configurer MySQL</title>
+ <sect3>
+ <title>Guide pour les distributions linux utilisant des RPM</title>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ </sect3>
+ <sect3>
+ <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>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <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>
+ </sect4>
+ <sect4>
+ <title>En cas de problème</title>
+ <sect5>
+ <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>
+ </sect5>
+ <sect5>
+ <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>
+ </sect5>
+ </sect4>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Configurer PostgreSQL</title>
+ <simpara>
+ Suite à une bogue dans le framework de persistance que nous utilisons, Scarab
+ ne fonctionnera pas tel quel avec PostgreSQL. Par chance, la solution de ce
+ problème est simple, il suffit d'exécuter un script pour contourner
+ le problème.
+ </simpara>
+ <simpara>
+ This script must be run by a user with sufficient privileges, which
+ generally means the user that originally created and initialised the
+ PostgreSQL database. Typically this user will be 'postgres'.
+ </simpara>
+ <simpara>
+ Ce script se trouve dans la distribution de Scarab sous <computeroutput>src/sql/postgresql/hack-db.sql</computeroutput>;
+ il peut être exécuté de différentes manières, par exemple en ligne de commande :
+ </simpara>
+ <informalexample>
+ <programlisting>postgres> psql scarab < hack-db.sql</programlisting>
+ </informalexample>
+ <simpara>
+ où 'scarab' est le nom de la base de données de Scarab, et 'postgres' est
+ l'utilisateur "système" PostgreSQL.
+ Sinon, on peut aussi lancer cette commande à la console interactive psql :
+ </simpara>
+ <informalexample>
+ <programlisting>scarab=> \i hack-db.sql</programlisting>
+ </informalexample>
+ </sect2>
+ <sect2>
+ <title>Préparer et configurer Oracle</title>
+ <sect3>
+ <title>Récupérer les drivers JDBC</title>
+ <simpara>Pour des raisons de licence, le jar contenant le pilote JDBC d'Oracle ne peut pas être inclus dans la distribution de Scarab.</simpara>
+ <simpara>Vous devez le récupérer vous-même dans votre distribution Oracle (ou depuis Oracle Technology Network: <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html">http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html</ulink>). À moins d'avoir une raison impérative de faire autrement, prenez les tout derniers pilotes: ils sont compatibles avec d'anciennes versions d'Oracle et sont beaucoup plus performants que les anciennes versions.</simpara>
+ <simpara>Le jar dont vous avez besoin s'appelle probablement <computeroutput>classes12.jar</computeroutput> (pour les JDK 1.2 et 1.3) ou <computeroutput>ojdbc14.jar</computeroutput> (pour les SDK 1.4 et 1.5). Copiez ce jar dans le répertoire <computeroutput>$SCARAB/lib</computeroutput> (c'est-à -dire le répertoire lib directement à la racine de votre distribution Scarab. Dans une installation à neuf de Scarab, ce répertoire est normalement vide, à l'exception d'un fichier README. C'est normal, il est rempli au cours du processus de build.</simpara>
+ </sect3>
+ <sect3>
+ <title>Configurer l'accès à votre base Oracle</title>
+ <simpara>Dans le fichier <computeroutput>build.properties</computeroutput> que vous allez constituer à l'étape 3 ci-dessous, vous devrez configurer l'accès à votre base de données Oracle.</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.host=localhost
+scarab.database.port=
+scarab.database.url=
+scarab.database.admin.url=
+scarab.database.type=oracle
+scarab.database.jdbc.driver=oracle.jdbc.driver.OracleDriver
+scarab.database.username=scarab
+scarab.database.password=secret
+scarab.database.admin.username=scott
+scarab.database.admin.password=tiger
+ </programlisting>
+ </informalexample>
+ </sect3>
+ <sect3>
+ <title>Résoudre un problème relatif aux LOBs</title>
+ <simpara>Pour utiliser des Large OBjects (LOBs), tels que des BLOBs (Binary Large OBjects) ou des CLOBs (Character Large OBjects) il est nécessaire d'instancier des classes Oracle (pas les classes génériques JDBC) et la couche de persistance que Scarab utilise pour l'instant, Torque, ne le permet pas. Un moyen de contourner ce problème est d'utiliser des VARCHARs en lieu et place des LOBs. Pour cela, il vous faudra éditer le fichier <computeroutput>webapps/scarab/WEB-INF/sql/turbine.sql</computeroutput> après avoir construit Scarab (voir la section suivante), et remplacer <computeroutput>BLOB</computeroutput> par <computeroutput>VARCHAR2(4000)</computeroutput><footnote><simpara>Vous pouvez aussi éditer <computeroutput>webapps/scarab/WEB-INF/src/torque/templates/sql/base/oracle/db.props</computeroutput> et changer <computeroutput>VARBINARY = BLOB</computeroutpu
t> en <computeroutput>VARBINARY = VARCHAR2(4000)</computeroutput> -- ça revient au même mais survit aux rebuilds.</simpara></footnote></simpara>
+ </sect3>
+ <sect3>
+ <title>Utiliser Oracle 10g XE sur la même machine Scarab</title>
+ <simpara>Juste un petit avertissement si vous comptez utiliser Scarab sur la même machine qu'Oracle 10g XE. Scarab et la web app d'administration d'Oracle écoutent par défaut sur le même port (8080), ce qui va provoquer un conflit.</simpara>
+ <simpara>Pour forcer Scarab à écouter sur un autre port, donnez à la propriété <computeroutput>scarab.http.port</computeroutput> une valeur de votre choix et éditez le fichier <computeroutput>./tomcat/conf.server.xml</computeroutput> pour configurer Tomcat et le faire écouter sur un autre port.</simpara>
+ <simpara>Pour changer le port sur lequel écoute la web app d'administration d'Oracle, consultez la documentation d'Oracle 10g XE.</simpara>
+ </sect3>
</sect2>
</sect1>
<sect1>
@@ -291,42 +667,14 @@
</sect2>
<sect2>
<title>Etape 4: Construire Scarab</title>
- <para>Il y a deux moyens de construire Scarab:</para>
- <orderedlist>
- <listitem>
- <simpara>Avec Maven 1:</simpara>
- <orderedlist>
- <listitem>
- <simpara>Allez dans le répertoire $SCARAB_ROOT</simpara>
- </listitem>
- <listitem>
- <simpara>Lancez Maven de la manière suivante :</simpara>
- <simpara><computeroutput>maven war -Dmaven.test.skip</computeroutput></simpara>
- <note>
- <simpara>
- <computeroutput>-Dmaven.test.skip</computeroutput> évite d'exécuter les tests unitaires.
- Si cela ne vous pose pas de problème d'exécuter les tests, il vous suffit de taper
- "maven war" mais attendez-vous à un allongement significatif du temps d'exécution !
- Comme les tests sont conçus pour être exécutés avec une base de données, il est
- possible qu'ils échouent si la vôtre n'est pas encore configurée.
- </simpara>
- </note>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <simpara>Avec Ant:</simpara>
- <orderedlist>
- <listitem>
- <simpara>Allez dans le répertoire $SCARAB_ROOT/build </simpara>
- </listitem>
- <listitem>
- <simpara>Lancez Ant de la manière suivante :</simpara>
- <simpara>ant</simpara>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
+ <simpara>Allez dans le répertoire <computeroutput>$SCARAB_ROOT/build</computeroutput></simpara>
+ <simpara>Lancez Ant de la manière suivante :</simpara>
+ <simpara><computeroutput>ant</computeroutput></simpara>
+ <note>
+ <simpara>Si vous êtes un développeur, en particulier un développeur de Scarab, vous pouvez aussi construire Scarab avec Maven 1.</simpara>
+ <simpara>Cette façon de faire vous donne plus d'options et de possibilités, par exemple la faculté de lancer des tests unitaires.</simpara>
+ <simpara>Pour plus de détails, vous pouvez vous référer au chapitre 3 du Guide du Développeur.</simpara>
+ </note>
</sect2>
<sect2>
<title>Etape 5a: Créer la base de données</title>
@@ -370,31 +718,7 @@
<simpara>Référez-vous au fichier MIGRATION pour des instructions complémentaires sur la migration de vos données existantes.</simpara>
</sect2>
<sect2>
- <title>Etape 6: [OPTIONNELLE] Exécutez les tests</title>
- <simpara>Si vous lancez les tests à présent, ils s'exécuteront sur la base de données que vous venez de configurer. Tapez simplement</simpara>
- <simpara><computeroutput>maven test</computeroutput></simpara>
- <simpara>Le résultat des tests sera disponible dans <computeroutput>$(SCARAB_HOME)/target/test-results/</computeroutput>.</simpara>
- <simpara>Si vous souhaitez exécuter les tests dans un autre environnement de base de données, procédez comme suit :</simpara>
- <orderedlist>
- <listitem>
- <simpara><computeroutput>maven clean</computeroutput> (il vaut mieux partir sur une base saine pour exécuter les tests)</simpara>
- </listitem>
- <listitem>
- <simpara>Configurez votre fichier build.properties pour qu'il contienne au moins la valeur correcte de la propriété <computeroutput>scarab.database.type value</computeroutput></simpara>
- </listitem>
- <listitem>
- <simpara><computeroutput>maven war</computeroutput></simpara>
- </listitem>
- <listitem>
- <simpara><computeroutput>maven scarab:create-db</computeroutput> (assurez-vous de choisir la même base qu'auparavant!)</simpara>
- </listitem>
- <listitem>
- <simpara><computeroutput>maven test</computeroutput></simpara>
- </listitem>
- </orderedlist>
- </sect2>
- <sect2>
- <title>Etape 7: Démarrer Tomcat</title>
+ <title>Etape 6: Démarrer Tomcat</title>
<simpara>Sur Windows, faites un double clic sur le fichier <computeroutput>$SCARAB_HOME/tomcat/bin/startup.bat</computeroutput></simpara>
<simpara>Sur Unix/Linux, exécutez le script shell <computeroutput>$SCARAB_HOME/tomcat/bin/startup.sh</computeroutput></simpara>
<simpara>L'application web sera alors disponible comme il a été spécifié en utilisant les propriétés suivantes (voir à l'étape 3) :!</simpara>
Modified: branches/release/b21/www/book/maven-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/maven-en.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/maven-en.xml&p2=branches/release/b21/www/book/maven-en.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/maven-en.xml (original)
+++ branches/release/b21/www/book/maven-en.xml 2006-08-07 15:38:00-0700
@@ -11,4 +11,53 @@
<para>So you will need to install Maven 1 and refer to the Maven 1 documentation at this URL: <ulink url="http://maven.apache.org/maven-1.x/">http://maven.apache.org/maven-1.x/</ulink>
</para>
</sect1>
+ <sect1>
+ <title>Building Scarab with Maven</title>
+ <sect2>
+ <title>Normal (full) build</title>
+ <simpara>Go to the <computeroutput>$SCARAB_ROOT</computeroutput> directory.</simpara>
+ <simpara>Launch Maven:</simpara>
+ <simpara>maven war<computeroutput/>
+ </simpara>
+ </sect2>
+ <sect2>
+ <title>Quick build</title>
+ <simpara>Go to the <computeroutput>$SCARAB_ROOT</computeroutput> directory.</simpara>
+ <simpara>Launch Maven:</simpara>
+ <simpara>maven war -Dmaven.test.skip<computeroutput/>
+ </simpara>
+ <simpara>
+ <computeroutput>-Dmaven.test.skip</computeroutput> skips the execution of unit tests.
+ Scarab unit tests have been designed to be executed against a database; if yours is not (yet) configured, they will most certainly fail.
+ </simpara>
+ </sect2>
+ <sect2>
+ <title>Running the tests</title>
+ <simpara>Just launch:</simpara>
+ <simpara>
+ <computeroutput>maven test</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 another db environment, follow these steps:</simpara>
+ <orderedlist>
+ <listitem>
+ <simpara>
+ <computeroutput>maven clean</computeroutput> (you better start from scratch if you gonna test)</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Configure your <computeroutput>build.properties</computeroutput> to contain at least the correct <computeroutput>scarab.database.type</computeroutput> value.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>maven war</simpara>
+ </listitem>
+ <listitem>
+ <simpara>maven scarab:create-db (make sure you choose the same database than before!!)</simpara>
+ </listitem>
+ <listitem>
+ <simpara>maven test</simpara>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
</chapter>
Modified: branches/release/b21/www/book/maven-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/maven-fr.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/maven-fr.xml&p2=branches/release/b21/www/book/maven-fr.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/maven-fr.xml (original)
+++ branches/release/b21/www/book/maven-fr.xml 2006-08-07 15:38:00-0700
@@ -2,7 +2,7 @@
<chapter>
<title>Maven</title>
<abstract>
- <simpara>La plupart des utilisateurs de Scarab se servent probablement de Ant pour construire Scarab. En tant que développeur, vous aurez besoin de Maven pour avoir accès à toutes les fonctionnalités de développement, notamment la génération de la documentation.</simpara>
+ <simpara>La plupart des utilisateurs de Scarab se servent probablement de ant pour construire Scarab. En tant que développeur, vous aurez besoin de Maven pour avoir accès à toutes les fonctionnalités de développement, notamment la génération de la documentation.</simpara>
</abstract>
<sect1>
<title>Maven 1</title>
@@ -11,4 +11,58 @@
<para>Il vous faudra donc installer Maven 1 et vous référer à la documentation de Maven 1 à cette URL: <ulink url="http://maven.apache.org/maven-1.x/">http://maven.apache.org/maven-1.x/</ulink>
</para>
</sect1>
+ <sect1>
+ <title>Construire Scarab avec Maven</title>
+ <sect2>
+ <title>Build normal</title>
+ <simpara>Allez dans le répertoire <computeroutput>$SCARAB_ROOT</computeroutput>
+ </simpara>
+ <simpara>Lancez Maven de la manière suivante :</simpara>
+ <simpara>maven war<computeroutput/>
+ </simpara>
+ </sect2>
+ <sect2>
+ <title>Build abrégé</title>
+ <simpara>Allez dans le répertoire <computeroutput>$SCARAB_ROOT</computeroutput>
+ </simpara>
+ <simpara>Lancez Maven de la manière suivante :</simpara>
+ <simpara>maven war -Dmaven.test.skip<computeroutput/>
+ </simpara>
+ <simpara>
+ <computeroutput>-Dmaven.test.skip</computeroutput> évite d'exécuter les tests unitaires. Comme les tests sont conçus pour être exécutés avec une base de données, il est possible qu'ils échouent si la vôtre n'est pas encore configurée.</simpara>
+ </sect2>
+ <sect2>
+ <title>Exécuter les tests</title>
+ <simpara>Si vous lancez les tests à présent, ils s'exécuteront sur la base de données que vous avez configurée. Tapez simplement</simpara>
+ <simpara>
+ <computeroutput>maven test</computeroutput>
+ </simpara>
+ <simpara>Le résultat des tests sera disponible dans <computeroutput>$(SCARAB_HOME)/target/test-results/</computeroutput>.</simpara>
+ <simpara>Si vous souhaitez exécuter les tests dans un autre environnement de base de données, procédez comme suit :</simpara>
+ <orderedlist>
+ <listitem>
+ <simpara>
+ <computeroutput>maven clean</computeroutput> (il vaut mieux partir sur une base saine pour exécuter les tests)</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Configurez votre fichier <computeroutput>build.properties</computeroutput> pour qu'il contienne au moins la valeur correcte de la propriété <computeroutput>scarab.database.type value</computeroutput>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <computeroutput>maven war</computeroutput>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <computeroutput>maven scarab:create-db</computeroutput> (assurez-vous de choisir la même base qu'auparavant!)</simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <computeroutput>maven test</computeroutput>
+ </simpara>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
</chapter>
Modified: branches/release/b21/www/book/modules-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/modules-en.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/modules-en.xml&p2=branches/release/b21/www/book/modules-en.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/modules-en.xml (original)
+++ branches/release/b21/www/book/modules-en.xml 2006-08-07 15:38:00-0700
@@ -1,5 +1,52 @@
<!-- $Id -->
<chapter>
<title>Creating and managing modules</title>
- <simpara>[This chapter is being written.]</simpara>
+ <sect1>
+ <title>Creating a new module</title>
+ <simpara>From the home page, choose any module, if you have not done that already (creation of a new module cannot occur outside a context, but that is irrelevant with the task we want to perform).</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation0.png"/>
+ </screenshot>
+ <simpara>From a module home page, or from many other pages, you can reach the module administration functions, but you may need to double-click in the left margin to make the menu appear.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation1a.png"/>
+ </screenshot>
+ <screenshot>
+ <graphic fileref="images/module-creation1b.png"/>
+ </screenshot>
+ <simpara>From there, choose Modules, Manage modules and push the Create new button.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation2.png"/>
+ </screenshot>
+ <simpara>You may now enter the information about the module that you want to create.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation3.png"/>
+ </screenshot>
+ <simpara>Two fields are worth a particular attention.</simpara>
+ <simpara>
+ The <emphasis>Parent module</emphasis> determines at this time the module which will be used as a template, a model, for the module you are about to create.
+ Basically this means that the new module will "inherit" all Issue types and attributes from the parent module you choose.</simpara>
+ <caution>
+ <simpara>This "inheritance" occurs once and for all at the time of module creation. Issue types and attributes are copied from the parent to the new modules.</simpara>
+ <simpara>Modifications to the issue types and attributes of the parent module you choose now <emphasis>will not be propagated</emphasis> to the new module afterwards.</simpara>
+ <simpara>To say it yet another way, issue types and attributes are copied from the parent to the new module, not shared between them.</simpara>
+ </caution>
+ <simpara>The module parent will also appear in the modules lists. For instance, the <emphasis>Source</emphasis> module which has <emphasis>Pacman JVM</emphasis> as parent appears as such in the list:</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation3.png"/>
+ </screenshot>
+ <simpara>You can change the parent later (see next Section) if you want to change the display logic but that should not be the main reason of your parent module choice at creation time.</simpara>
+ </sect1>
+ <sect1>
+ <title>Editing a module</title>
+ <simpara>To edit the definition and properties of a module, choose <emphasis>Manage modules</emphasis> in the <emphasis>Admin</emphasis> menu, then choose the module.</simpara>
+ <simpara>The next screen is pretty self-explanatory.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-edition1.png"/>
+ </screenshot>
+ <simpara>You cannot delete a module but you can mark it as deleted. The module will no longer appear in the modules lists (though it will still appear, as deleted, in the <emphasis>Manage modules</emphasis> list if you ever want to recall it someday later).</simpara>
+ <screenshot>
+ <graphic fileref="images/module-edition2.png"/>
+ </screenshot>
+ </sect1>
</chapter>
Modified: branches/release/b21/www/book/modules-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/modules-fr.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/modules-fr.xml&p2=branches/release/b21/www/book/modules-fr.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/modules-fr.xml (original)
+++ branches/release/b21/www/book/modules-fr.xml 2006-08-07 15:38:00-0700
@@ -1,5 +1,52 @@
<!-- $Id -->
<chapter>
<title>Créer et gérer des modules</title>
- <simpara>[Ce chapitre est à écrire.]</simpara>
+ <sect1>
+ <title>Créer un nouveau module</title>
+ <simpara>À partir de la page d'accueil, sélectionnez un module si ce n'est déjà fait (la création d'un module ne peut se faire en dehors de tout contexte, mais c'est sans importance pour la tâche considérée).</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation0.fr.png"/>
+ </screenshot>
+ <simpara>Depuis la page d'accueil d'un module, ou à partir de la plupart des autres pages d'ailleurs, vous pouvez accéder aux fonctionnalités d'administration des modules mais il vous faudra peut-être double cliquer dans la marge de gauche pour faire apparaître le menu correspondant.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation1a.fr.png"/>
+ </screenshot>
+ <screenshot>
+ <graphic fileref="images/module-creation1b.fr.png"/>
+ </screenshot>
+ <simpara>Là , choisissez Modules, Gérer les modules et cliquez le bouton Créer nouveau.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation2.fr.png"/>
+ </screenshot>
+ <simpara>Vous pouvez maintenant entrer les informations relatives au module que vous voulez créer.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation3.fr.png"/>
+ </screenshot>
+ <simpara>Deux champs méritent une attention particulière à ce stade.</simpara>
+ <simpara>
+ Le champ <emphasis>Module parent</emphasis> détermine le module qui sera utilisé comme gabarit, comme modèle, pour le module que vous vous apprêtez à créer.
+ Cela veut dire que le nouveau module "héritera" de tous les types de fiches et attributs du module parent que vous choisissez.</simpara>
+ <caution>
+ <simpara>Cet "héritage" a donc lieu une fois pour toutes à la création du module. Les types de fiches et les attributs sont copiés du parent au nouveau module.</simpara>
+ <simpara>Les modifications ultérieures des types de fiches et attributs du module parent que vous choisissez maintenant <emphasis>ne seront pas propagées</emphasis> au module que vous créez.</simpara>
+ <simpara>Ou pour le dire encore d'une autre manière, les types de fiches et attributs sont copiés du module parent au nouveau module, ils ne sont pas partagés entre eux.</simpara>
+ </caution>
+ <simpara>Le module parent apparaît aussi dans les listes de modules. Par exemple, le module <emphasis>Source</emphasis> qui a <emphasis>Pacman JVM</emphasis> comme parent apparaît ainsi dans la liste :</simpara>
+ <screenshot>
+ <graphic fileref="images/module-creation3.fr.png"/>
+ </screenshot>
+ <simpara>Vous pouvez changer le parent dans un second temps (voir la section suivante) si vous voulez changer la logique de présentation des modules mais ce critère ne doit pas déterminer votre choix au moment de la création du module.</simpara>
+ </sect1>
+ <sect1>
+ <title>Éditer un module</title>
+ <simpara>Pour modifier la définition et les propriétés d'un module, cliquez <emphasis>Gérer les modules</emphasis> dans le menu <emphasis>Admin</emphasis>, puis cliquez le module.</simpara>
+ <simpara>L'écran suivant ne nécessite pas grande explication.</simpara>
+ <screenshot>
+ <graphic fileref="images/module-edition1.fr.png"/>
+ </screenshot>
+ <simpara>Vous ne pouvez pas supprimer complètement un module mais vous pouvez le marquer comme détruit (et donc le faire disparaître des opérations courantes). Le module n'apparaîtra plus dans les listes de modules (mais il apparaîtra encore, barré, dans la liste de l'écran <emphasis>Gérer les modules</emphasis> au cas où vous voudriez le réactiver un jour).</simpara>
+ <screenshot>
+ <graphic fileref="images/module-edition2.fr.png"/>
+ </screenshot>
+ </sect1>
</chapter>
Modified: branches/release/b21/www/book/scarab-admin-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/scarab-admin-en.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/scarab-admin-en.xml&p2=branches/release/b21/www/book/scarab-admin-en.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/scarab-admin-en.xml (original)
+++ branches/release/b21/www/book/scarab-admin-en.xml 2006-08-07 15:38:00-0700
@@ -3,6 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY install SYSTEM "install-en.xml">
<!ENTITY admin SYSTEM "admin-en.xml">
+ <!ENTITY subversion SYSTEM "subversion-en.xml">
]>
<!-- $Id -->
<book>
@@ -18,4 +19,5 @@
&install;
&admin;
+ &subversion;
</book>
Modified: branches/release/b21/www/book/scarab-admin-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/scarab-admin-fr.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/scarab-admin-fr.xml&p2=branches/release/b21/www/book/scarab-admin-fr.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/scarab-admin-fr.xml (original)
+++ branches/release/b21/www/book/scarab-admin-fr.xml 2006-08-07 15:38:00-0700
@@ -3,6 +3,7 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY install SYSTEM "install-fr.xml">
<!ENTITY admin SYSTEM "admin-fr.xml">
+ <!ENTITY subversion SYSTEM "subversion-fr.xml">
]>
<!-- $Id -->
<book>
@@ -18,4 +19,5 @@
&install;
&admin;
+ &subversion;
</book>
Modified: branches/release/b21/www/book/scarab-user-de.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/scarab-user-de.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/scarab-user-de.xml&p2=branches/release/b21/www/book/scarab-user-de.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/scarab-user-de.xml (original)
+++ branches/release/b21/www/book/scarab-user-de.xml 2006-08-07 15:38:00-0700
@@ -11,8 +11,7 @@
<!ENTITY bestpractices SYSTEM "bestpractices-en.xml">
<!ENTITY workflow SYSTEM "workflow1-en.xml">
<!ENTITY xml SYSTEM "xml-import-export-en.xml">
- <!ENTITY ide SYSTEM "ide-en.xml">
- <!ENTITY subversion SYSTEM "subversion-en.xml">
+ <!ENTITY integration SYSTEM "integration-en.xml">
]>
<!-- $Id -->
<book>
@@ -42,11 +41,10 @@
&modules;
&bestpractices;
&workflow;
- &xml;
</part>
<part>
- <title>Scarab for developers</title>
- &ide;
- &subversion;
+ <title>Advanced topics</title>
+ &xml;
+ &integration;
</part>
</book>
Modified: branches/release/b21/www/book/scarab-user-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/scarab-user-en.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/scarab-user-en.xml&p2=branches/release/b21/www/book/scarab-user-en.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/scarab-user-en.xml (original)
+++ branches/release/b21/www/book/scarab-user-en.xml 2006-08-07 15:38:00-0700
@@ -11,8 +11,7 @@
<!ENTITY bestpractices SYSTEM "bestpractices-en.xml">
<!ENTITY workflow SYSTEM "workflow1-en.xml">
<!ENTITY xml SYSTEM "xml-import-export-en.xml">
- <!ENTITY ide SYSTEM "ide-en.xml">
- <!ENTITY subversion SYSTEM "subversion-en.xml">
+ <!ENTITY integration SYSTEM "integration-en.xml">
]>
<!-- $Id -->
<book>
@@ -42,11 +41,10 @@
&modules;
&bestpractices;
&workflow;
- &xml;
</part>
<part>
- <title>Scarab for developers</title>
- &ide;
- &subversion;
+ <title>Advanced topics</title>
+ &xml;
+ &integration;
</part>
</book>
Modified: branches/release/b21/www/book/scarab-user-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/book/scarab-user-fr.xml?view=diff&rev=10256&p1=branches/release/b21/www/book/scarab-user-fr.xml&p2=branches/release/b21/www/book/scarab-user-fr.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/book/scarab-user-fr.xml (original)
+++ branches/release/b21/www/book/scarab-user-fr.xml 2006-08-07 15:38:00-0700
@@ -11,8 +11,7 @@
<!ENTITY bestpractices SYSTEM "bestpractices-fr.xml">
<!ENTITY workflow SYSTEM "workflow1-fr.xml">
<!ENTITY xml SYSTEM "xml-import-export-fr.xml">
- <!ENTITY ide SYSTEM "ide-fr.xml">
- <!ENTITY subversion SYSTEM "subversion-fr.xml">
+ <!ENTITY integration SYSTEM "integration-fr.xml">
]>
<!-- $Id -->
<book>
@@ -42,11 +41,10 @@
&modules;
&bestpractices;
&workflow;
- &xml;
</part>
<part>
- <title>Scarab pour développeurs</title>
- &ide;
- &subversion;
+ <title>Aller plus loin avec Scarab</title>
+ &xml;
+ &integration;
</part>
</book>
Modified: branches/release/b21/www/users.html
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/www/users.html?view=diff&rev=10256&p1=branches/release/b21/www/users.html&p2=branches/release/b21/www/users.html&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/www/users.html (original)
+++ branches/release/b21/www/users.html 2006-08-07 15:38:00-0700
@@ -10,6 +10,12 @@
<tr>
<td bgcolor="#f0f0f0">
+ <p>
+ There are quite a few companies using Scarab in production. Some of them
+ have allowed us to publish their contact data. We would appreciate to also
+ find your company mentioned here. So in case it applies, please send a short
+ info to the Scarab devlist containg the contact data and we will add you to the list.
+ </p>
<table border="1">
<tr>
<th align="left">company</th>
@@ -21,7 +27,7 @@
<td valign="top"><a href="http://www.saxess.de">Saxess Software Design</a></td>
<td valign="top">bugtracking</td>
<td valign="top"><a href="mailto:[email protected] ">Hussayn Dabbous</a></td>
- <td valign="top"><img href="http://www.saxess.de/system/modules/de.saxess.templates/resources/company-logo.gif" border="0"/></td>
+ <td align="middle" valign="top" bgcolor="white"><img src="http://www.saxess.net/images/company-logo.gif" border="0"/></td>
</tr>
<tr>
<td valign="top"><a href="http://www.beachsolutions.com">Beach Solutions Limited</a></td>
@@ -39,7 +45,20 @@
<td valign="top">bug tracking, requirements management</td>
<td valign="top">Dr. Joachim Schnitter</td>
</tr>
-
+ <tr>
+ <td valign="top"><a href="http://www.kobold.com.au">KoBold Systems</a></td>
+ <td valign="top">Defect/Enhancement tracking</td>
+ <td valign="top"><a href="mailto:[email protected] ">Daniel F Garcia</a></td>
+ <td align="middle" valign="top"><img src="http://www.kobold.com.au/KoboldSystems160x75.gif" border="0"/></td>
+ </tr>
+ <!--
+ <tr>
+ <td valign="top"><a href=""></a></td>
+ <td valign="top"></td>
+ <td valign="top"><a href="mailto:"></a></td>
+ <td align="middle" valign="top"><img src="" border="0"/></td>
+ </tr>
+ -->
</table>
</tr>
Modified: branches/release/b21/xdocs/databases/index.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/b21/xdocs/databases/index.xml?view=diff&rev=10256&p1=branches/release/b21/xdocs/databases/index.xml&p2=branches/release/b21/xdocs/databases/index.xml&r1=10255&r2=10256
==============================================================================
--- branches/release/b21/xdocs/databases/index.xml (original)
+++ branches/release/b21/xdocs/databases/index.xml 2006-08-07 15:38:00-0700
@@ -28,17 +28,17 @@
<br/><a href="mailto:[email protected] ">jorgeuriarte</a>
</td>
<td>
- best test coverage, because preferred RDB in Scarab-development.
+ Best test coverage, because preferred RDB in Scarab-development.
</td>
</tr>
<tr>
<td><a href="postgresql.html">PostgreSQL</a></td>
- <td><font color="orange"><b>Partial</b></font></td>
+ <td><font color="orange"><b>Full</b></font></td>
<td>
<a href="mailto:[email protected] ">jorgeuriarte</a>
<br/><a href="[email protected] ">ptillemans</a>
</td>
- <td>Needed help from the community to certify it works perfectly.</td>
+ <td>Tested with milestone 21.</td>
</tr>
<tr>
@@ -48,17 +48,17 @@
<a href="mailto:[email protected] ">jorgeuriarte</a><br/>
<a href="mailto:[email protected] ">Mick Wever</a>
</td>
- <td>Needed help from the community to certify it works perfectly.</td>
+ <td>Further help needed from the community to certify it works perfectly.</td>
</tr>
<tr>
- <td><a href="hypersonic.html">Hypersonic</a></td>
+ <td><a href="hypersonic.html">HSQLDB (was: Hypersonic SQL)</a></td>
<td><font color="red"><b>No</b></font></td>
<td>
<a href="mailto:[email protected] ">hdabbous</a>
<br/><a href="[email protected] ">ptillemans</a>
</td>
- <td>integrated, but SQL-errors. Support deferred after release 1.0</td>
+ <td>Integrated, but SQL-errors. Support deferred after release 1.0</td>
</tr>
<tr>
@@ -93,7 +93,7 @@
are verified to work with the current release and the integration
documentation has been verified.
- Databases marked as "<font color="orange"><b>Partial supported</b></font>"
+ Databases marked as "<font color="orange"><b>Partial support</b></font>"
have been tested with the current release, but either the integration
is complex, or not well documented. Help from the comunity is needed.