Scarab commit: svn commit: r10238 - trunk/www/book
[email protected] 4 Aug 2006 21:25:13 -0000
Newsgroups
gmane.comp.java.scarab.cvs
Message-ID
<[email protected] >
Author: jfelfouly
Date: 2006-08-04 14:25:13-0700
New Revision: 10238
Modified:
trunk/www/book/install-en.xml
trunk/www/book/install-fr.xml
trunk/www/book/maven-en.xml
trunk/www/book/maven-fr.xml
Log:
Installation information much improved, with additional info coming from various sources. Building Scarab with Maven moved to Developer's Guide (my option).
Modified: trunk/www/book/install-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/install-en.xml?view=diff&rev=10238&p1=trunk/www/book/install-en.xml&p2=trunk/www/book/install-en.xml&r1=10237&r2=10238
==============================================================================
--- trunk/www/book/install-en.xml (original)
+++ trunk/www/book/install-en.xml 2006-08-04 14:25:13-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,23 +111,159 @@
<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>
+ <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>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>
</sect1>
<sect1>
+ <title>Setting up and configuring your database for Scarab</title>
+ <sect2>
<title>Installing and configuring MySQL</title>
- <sect2>
+ <sect3>
<title>Guide for Linux with RPM packages</title>
- <sect3>
+ <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 will find an appropriate distribution through the <ulink url="http://www.mysql.com">MySQL website</ulink>.</simpara>
<simpara>You can follow the instructions from the MySQL documentation. We shall give here summary info only.</simpara>
- </sect3>
- <sect3>
+ </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>
@@ -147,8 +271,8 @@
rpm -i MySQL-server-4.0.22-0.i386.rpm MySQL-shared-4.0.22-0.i386.rpm MySQL-client-4.0.22-0.i386.rpm
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -157,12 +281,12 @@
safe_mysqld
</programlisting>
</informalexample>
- </sect3>
- </sect2>
- <sect2>
+ </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>
- <sect3>
+ <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>
@@ -180,8 +304,8 @@
</informalexample>
<simpara>You may need to reboot(!) although I am not sure about this. After reboot, ensure that your operating system has not manipulated the entry in your /etc/hosts file. I have no idea what to do if this happens... (FIXME: add a recipe for this situation)
</simpara>
- </sect3>
- <sect3>
+ </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>
@@ -189,8 +313,8 @@
<computeroutput>mysql -u root mysql</computeroutput>
</simpara>
<simpara>Now you should have access to the administration database of your MySQL instance. If you are rejected, something out of the trail happened. Either your database is corrupted or someone else has installed the database and has set up security. In that case you may need to ask your administrator to give you access to the "mysql" database in order to proceed with the next step.</simpara>
- </sect3>
- <sect3>
+ </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>
@@ -226,8 +350,8 @@
1 row in set (0.00 sec)
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -255,8 +379,8 @@
+-----------+--------+-------------------------------------------+
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -272,8 +396,8 @@
<note>
<simpara>This step is NOT required for the Scarab setup, but doing so ensures that your privilege settings for the Scarab administration user are correct and work as needed. </simpara>
</note>
- </sect3>
- <sect3>
+ </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>
@@ -299,8 +423,8 @@
<note>
<simpara>The database.username and password are later used to automatically create(!) an additional user 'scarab' with password 'baracs'. So don't bother yourself with setting up other users except the admin user !</simpara>
</note>
- </sect3>
- <sect3>
+ </sect4>
+ <sect4>
<title>Step VII - Build scarab</title>
<simpara>Go to the build directory and launch ant</simpara>
<informalexample>
@@ -336,8 +460,8 @@
[echo]
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -354,10 +478,10 @@
ant create-db
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </sect4>
+ <sect4>
<title>Troubleshooting</title>
- <sect4>
+ <sect5>
<title>If nothing helps</title>
<simpara>Here are a couple of additional links to help you solve the permissions problem:</simpara>
<itemizedlist>
@@ -372,8 +496,8 @@
</simpara>
</listitem>
</itemizedlist>
- </sect4>
- <sect4>
+ </sect5>
+ <sect5>
<title>Last resort (applies to some linux distros)</title>
<para>
If nothing helps, check this (thanks to Josh Howe for investigation).
@@ -394,8 +518,75 @@
the host where your Java code is running to the MySQL server on the port
that MySQL is listening to (by default, 3306).
</para>
- </sect4>
- </sect3>
+ </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>
@@ -456,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>
@@ -545,32 +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: trunk/www/book/install-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/install-fr.xml?view=diff&rev=10238&p1=trunk/www/book/install-fr.xml&p2=trunk/www/book/install-fr.xml&r1=10237&r2=10238
==============================================================================
--- trunk/www/book/install-fr.xml (original)
+++ trunk/www/book/install-fr.xml 2006-08-04 14:25:13-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,6 +113,18 @@
<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>
@@ -133,17 +133,141 @@
<para>L'essentiel de votre travail lors de l'installation portera dans un premier temps sur le répertoire ./build.</para>
</sect3>
</sect2>
+ <sect2>
+ <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>
</sect1>
<sect1>
+ <title>Configurer votre base de données pour Scarab</title>
+ <sect2>
<title>Installer et configurer MySQL</title>
- <sect2>
+ <sect3>
<title>Guide pour les distributions linux utilisant des RPM</title>
- <sect3>
+ <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>
- </sect3>
- <sect3>
+ </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>
@@ -151,8 +275,8 @@
rpm -i MySQL-server-4.0.22-0.i386.rpm MySQL-shared-4.0.22-0.i386.rpm MySQL-client-4.0.22-0.i386.rpm
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -161,12 +285,12 @@
safe_mysqld
</programlisting>
</informalexample>
- </sect3>
- </sect2>
- <sect2>
+ </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>
- <sect3>
+ <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>
@@ -183,8 +307,8 @@
</programlisting>
</informalexample>
<simpara>Il se peut que vous ayiez à redémarrer la machine (mais ce n'est pas certain). Après le redémarrage, assurez-vous que le système d'exploitation n'a pas manipulé l'entrée de votre fichier /etc/hosts. Nous n'avons pas d'idée à vous suggérer si c'était le cas (mais si vous en aviez une, nous serions heureux de la connaître !).</simpara>
- </sect3>
- <sect3>
+ </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>
@@ -192,8 +316,8 @@
<computeroutput>mysql -u root mysql</computeroutput>
</simpara>
<simpara>Vous devez maintenant avoir accès à la base de données d'administration de votre instance de MySQL. Si votre demande de connexion est rejetée, quelque chose d'inattendu a dû se produire. Soit votre base de données est corrompue, soit quelqu'un d'autre a installé la base et a paramétré la sécurité. Dans ce cas, vous devrez peut-être demander à votre administrateur de vous donner accès à la base de données "mysql" pour pouvoir passer à l'étape suivante.</simpara>
- </sect3>
- <sect3>
+ </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>
@@ -229,8 +353,8 @@
1 row in set (0.00 sec)
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -258,8 +382,8 @@
+-----------+--------+-------------------------------------------+
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -275,8 +399,8 @@
<note>
<simpara>Cette étape n'est PAS requise par le paramétrage de Scarab mais procéder ainsi permet de s'assurer que les privilèges définis pour l'administrateur de Scarab sont corrects et fonctionnent comme prévu.</simpara>
</note>
- </sect3>
- <sect3>
+ </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>
@@ -302,8 +426,8 @@
<note>
<simpara>Les propriétés database.username et database.password seront utilisées plus loin dans le processus pour créer automatiquement un utilisateur de base de données 'scarab' authentifié par le mot de passe 'baracs'. Il n'est donc pas utile de vous embêter à créer et paramétrer vous mêmes d'autres utilisateurs que l'utilisateur admin.</simpara>
</note>
- </sect3>
- <sect3>
+ </sect4>
+ <sect4>
<title>Étape VII - Construire Scarab</title>
<simpara>Allez dans le répertoire build et lancez la commande ant.</simpara>
<informalexample>
@@ -339,8 +463,8 @@
[echo]
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </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>
@@ -357,10 +481,10 @@
ant create-db
</programlisting>
</informalexample>
- </sect3>
- <sect3>
+ </sect4>
+ <sect4>
<title>En cas de problème</title>
- <sect4>
+ <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>
@@ -375,8 +499,8 @@
</simpara>
</listitem>
</itemizedlist>
- </sect4>
- <sect4>
+ </sect5>
+ <sect5>
<title>En dernier recours (s'applique à certaines distributions linux)</title>
<para>
Si ça ne marche toujours pas, vérifiez encore ceci
@@ -399,8 +523,75 @@
le firewall pour permettre les connexions TCP/IP depuis la machine qui héberge Scarab
jusqu'au serveur MySQL sur le port sur lequel MySQL écoute (par défaut, 3306).
</para>
- </sect4>
- </sect3>
+ </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>
@@ -476,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>
@@ -555,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: trunk/www/book/maven-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/maven-en.xml?view=diff&rev=10238&p1=trunk/www/book/maven-en.xml&p2=trunk/www/book/maven-en.xml&r1=10237&r2=10238
==============================================================================
--- trunk/www/book/maven-en.xml (original)
+++ trunk/www/book/maven-en.xml 2006-08-04 14:25:13-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: trunk/www/book/maven-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/trunk/www/book/maven-fr.xml?view=diff&rev=10238&p1=trunk/www/book/maven-fr.xml&p2=trunk/www/book/maven-fr.xml&r1=10237&r2=10238
==============================================================================
--- trunk/www/book/maven-fr.xml (original)
+++ trunk/www/book/maven-fr.xml 2006-08-04 14:25:13-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>