Scarab commit: svn commit: r10887 - branches/release/0.22: . www/book xdocs xdocs/databases xdocs/howto
Johannes Höchstädter <[email protected]>
| Newsgroups | gmane.comp.java.scarab.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: jhoech
Date: 2010-02-03 04:12:05-0800
New Revision: 10887
Added:
branches/release/0.22/xdocs/faq.fml
Removed:
branches/release/0.22/www/book/admin-fr.xml
branches/release/0.22/www/book/ant-fr.xml
branches/release/0.22/www/book/architecture-fr.xml
branches/release/0.22/www/book/bestpractices-fr.xml
branches/release/0.22/www/book/eclipse-fr.xml
branches/release/0.22/www/book/ergonomy-fr.xml
branches/release/0.22/www/book/install-fr.xml
branches/release/0.22/www/book/integration-fr.xml
branches/release/0.22/www/book/intro-fr.xml
branches/release/0.22/www/book/issues-fr.xml
branches/release/0.22/www/book/login-de.xml
branches/release/0.22/www/book/login-fr.xml
branches/release/0.22/www/book/maven-fr.xml
branches/release/0.22/www/book/modules-fr.xml
branches/release/0.22/www/book/netbeans-fr.xml
branches/release/0.22/www/book/queries-fr.xml
branches/release/0.22/www/book/reports-fr.xml
branches/release/0.22/www/book/scarab-admin-fr.xml
branches/release/0.22/www/book/scarab-dev-fr.xml
branches/release/0.22/www/book/scarab-user-de.xml
branches/release/0.22/www/book/scarab-user-fr.xml
branches/release/0.22/www/book/schema-fr.xml
branches/release/0.22/www/book/subversion-fr.xml
branches/release/0.22/www/book/superadmin-fr.xml
branches/release/0.22/www/book/workflow1-fr.xml
branches/release/0.22/www/book/workflow2-fr.xml
branches/release/0.22/www/book/xml-import-export-fr.xml
branches/release/0.22/www/book/xml-rpc-fr.xml
branches/release/0.22/xdocs/faqs.fml
branches/release/0.22/xdocs/howto/tuning-howto.xml
branches/release/0.22/xdocs/maven_goals.xml
branches/release/0.22/xdocs/maven_properties.xml
Modified:
branches/release/0.22/maven.xml
branches/release/0.22/project.xml
branches/release/0.22/properties.xsl
branches/release/0.22/www/book/install-en.xml
branches/release/0.22/www/book/modules-en.xml
branches/release/0.22/www/book/queries-en.xml
branches/release/0.22/www/book/reports-en.xml
branches/release/0.22/xdocs/databases/database_independence.xml
branches/release/0.22/xdocs/databases/hypersonic.xml
branches/release/0.22/xdocs/databases/index.xml
branches/release/0.22/xdocs/databases/scarabdb.png
branches/release/0.22/xdocs/guides.xml
branches/release/0.22/xdocs/howto/ant-build-howto.xml
branches/release/0.22/xdocs/howto/build-docs-howto.xml
branches/release/0.22/xdocs/howto/build-howto.xml
branches/release/0.22/xdocs/howto/customize-howto.xml
branches/release/0.22/xdocs/howto/firewall-howto.xml
branches/release/0.22/xdocs/howto/maven-build-howto.xml
branches/release/0.22/xdocs/howto/release-howto.xml
branches/release/0.22/xdocs/howto/windowsdomain-howto.xml
branches/release/0.22/xdocs/index.xml
branches/release/0.22/xdocs/navigation.xml
Log:
ENH - Revised documentation files and related configurations committed.
DEL - Some files got deleted because they are merged.
ENH - Content is revised, but there are no major additions.
DEL - DocBook files for French and German deleted, because they are not longer supported.
Modified: branches/release/0.22/maven.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/maven.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/maven.xml (original)
+++ branches/release/0.22/maven.xml 2010-02-03 04:12:05-0800
@@ -246,20 +246,15 @@
</ant:ant>
</postGoal>
+ <!-- =============================================== -->
+ <!-- build docs before maven site is generated -->
+ <!-- =============================================== -->
<preGoal name="site">
<attainGoal name="sdocbook"/>
<!-- <attainGoal name="torque:doc"/> -->
<attainGoal name="javadoc"/>
<!-- <attainGoal name="scarab:check-locales"/> -->
</preGoal>
-
- <!-- there are inconsistencies -->
- <!-- Sometimes the name faq.html ist used -->
- <!-- in other cases it is faqs.html -->
- <!-- this is to be corrected later -->
- <postGoal name="site">
- <ant:copy file="target/docs/faqs.html" tofile="target/docs/faq.html" />
- </postGoal>
<postGoal name="clean:clean">
<ant:ant antfile="build/build.xml"
@@ -284,7 +279,7 @@
<goal name="scarab:check-locales"
prereqs="java:compile"
description="Check language translations">
- <ant:taskdef
+ <ant:taskdef
name="checkLocaleBundles"
classname="org.tigris.scarab.util.build.AntL10AnalysisTask" >
<ant:classpath>
Modified: branches/release/0.22/project.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/project.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/project.xml (original)
+++ branches/release/0.22/project.xml 2010-02-03 04:12:05-0800
@@ -113,8 +113,8 @@
<developer>
<name>Johannes Hoechstaedter</name>
<id>jhoech</id>
- <email>jhoechstaedter_at_memocomp_dot_com</email>
- <organization>memoComp</organization>
+ <email>opensource_at_memocomp_dot_de</email>
+ <organization>www.memocomp.de</organization>
</developer>
</developers>
@@ -769,7 +769,7 @@
<type>plugin</type>
</dependency>
- <dependency>
+ <dependency>
<groupId>statcvs</groupId>
<artifactId>maven-statcvs-plugin</artifactId>
<version>2.4</version>
@@ -934,14 +934,14 @@
<!--report>maven-file-activity-plugin</report-->
<!--report>maven-javadoc-plugin</report-->
<!--report>maven-jxr-plugin</report-->
- <report>maven-junit-report-plugin</report>
- <report>maven-tasklist-plugin</report>
+ <!--report>maven-junit-report-plugin</report-->
+ <!--report>maven-tasklist-plugin</report-->
<!--report>maven-jcoverage-plugin</report-->
<!--report>maven-simian-plugin</report-->
- <report>maven-pmd-plugin</report>
- <report>maven-tasks-plugin</report>
- <report>maven-findbugs-plugin</report>
+ <!--report>maven-pmd-plugin</report-->
+ <!--report>maven-tasks-plugin</report-->
+ <!--report>maven-findbugs-plugin</report-->
<!--report>maven-statcvs-plugin</report-->
</reports>
</project>
Modified: branches/release/0.22/properties.xsl
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/properties.xsl?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/properties.xsl (original)
+++ branches/release/0.22/properties.xsl 2010-02-03 04:12:05-0800
@@ -29,7 +29,8 @@
<tr>
<th>Property name</th>
<th>Type</th>
- <th>Comment</th>
+ <th>Comment</th>
+ <th>Details</th>
</tr>
<xsl:apply-templates />
</table>
@@ -45,6 +46,7 @@
<td><xsl:value-of select="name" /></td>
<td><xsl:value-of select="type" /></td>
<td><xsl:value-of select="comment" /></td>
+ <td><xsl:value-of select="details" /></td>
</tr>
</xsl:template>
Removed: branches/release/0.22/www/book/admin-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/admin-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/ant-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/ant-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/architecture-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/architecture-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/bestpractices-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/bestpractices-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/eclipse-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/eclipse-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/ergonomy-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/ergonomy-fr.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/www/book/install-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/install-en.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/www/book/install-en.xml (original)
+++ branches/release/0.22/www/book/install-en.xml 2010-02-03 04:12:05-0800
@@ -57,7 +57,7 @@
<sect4>
<title>MySQL</title>
<para>MySQL is the DBMS on which Scarab has been developed and fully tested. If you don't have any particular reason to choose a database or another to run Scarab, MySQL should be your first choice.</para>
- <para>Which version to choose? Scarab will work with any 3.x or 4.x version of MySQL. It could happen in the future that the support of version 3 could be dropped to use the transactional functionalities that are available only in version 4. So, if you don't have a particular reason to choose a particular version, you may choose long term peace of mind and use a version 4.x. from the start.</para>
+ <para>Which version to choose? Scarab will work with any 3.x or later version of MySQL. It could happen in the future that the support of version 3 could be dropped to use the transactional functionalities that are available only in version 4. So, if you don't have a particular reason to choose a particular version, you may choose long term peace of mind and use a version 4.x or higher from the start.</para>
<para>MySQL is open-source software, and it is available for free on Linux, Windows and a few other platforms (commercial licences and support are available for a fee).</para>
</sect4>
<sect4>
@@ -130,7 +130,162 @@
<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>
+ </sect1>
+ <sect1>
+ <title>Setting up and configuring your database for Scarab</title>
+ <sect2>
+ <title>Configuring MySQL</title>
+ <sect3>
+ <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 should follow the instructions from the MySQL documentation. In this documentation you will find Scarab dependent info only. It is assumed you want to run the MySQL database and scarab on the same host namely 'localhost'. Adapt this to your needs.</simpara>
+ </sect3>
+ <sect3>
+ <title>Check the /etc/hosts file (unix only)</title>
+ <simpara>If you plan to run MySQL on localhost, you must check the corresponding entry in your /etc/hosts file. We have seen problems when the localhost entry is defined as in the following example:</simpara>
+ <informalexample>
+ <programlisting>
+127.0.0.1 localhost.localdomain localhost (seen on debian)
+127.0.0.1 linux localhost (seen on Suse)
+ </programlisting>
+ </informalexample>
+ <simpara>If you see similar entries, revert the order so that "localhost" appears first:</simpara>
+ <informalexample>
+ <programlisting>
+127.0.0.1 localhost localhost.localdomain (seen on debian)
+127.0.0.1 localhost linux (seen on Suse)
+ </programlisting>
+ </informalexample>
+ <simpara>You may need to reboot. Although I am not sure about this. After reboot, ensure that your operating system has not manipulated the entry in your /etc/hosts file. I have no idea what to do if this happens... (FIXME: add a recipe for this situation)
+</simpara>
+ </sect3>
+ <sect3>
+ <title>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>
+ <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>
+ <note>
+ <simpara>You will need ALL choices above later to add them to the {{build.properties}} of Scarab.</simpara>
+ </note>
+ </sect3>
+ <sect3>
+ <title>Test the settings</title>
+ <caution>
+ <simpara>This step is for safety only. It 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>
+ </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>
+ </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 during build, 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 <c
omputeroutput>VARBINARY = VARCHAR2(4000)</computeroutput> -- that is a slightly more persistent modification.</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>
+ <title>Simple Scarab build</title>
+ <sect2>
+ <title>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 (just keep them in mind for a minute).</simpara>
+ <simpara>Now edit build.properties according your special needs. For database settings the following properties are important:</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>There are other relevant database specific properties, but usually they are generated from the above settings. Two more additional properties you should take care of are:</simpara>
+ <informalexample>
+ <programlisting>
+scarab.database.type=mysql #unchanged
+scarab.database.port=**GENERATED** #unchanged
+ </programlisting>
+ </informalexample>
+ <simpara>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>
+ <simpara>The properties for username and password are later used to automatically create an additional user for Scarab. Don't bother yourself with setting up other users except the admin user!</simpara>
+ <simpara>There are several more properties you can think of here, except database settings. You may have a look at Scarab's peoperty guide for more informations.</simpara>
+ </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>
@@ -252,253 +407,92 @@
</sect4>
</sect3>
</sect2>
- </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>
+ <sect2>
+ <title>Build Scarab</title>
+ <simpara>Go to the build directory and launch ant</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
+ ant
</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>
+ <simpara>This command simply compiles the source code. Run the following command to get a WAR file for Scarab:</simpara>
<informalexample>
<programlisting>
-mysql_install_db
-safe_mysqld
+ ant war
</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>
+ <simpara>The compiled and archived output should be found in <computeroutput>/target</computeroutput> directory of Scarab.</simpara>
+ </sect2>
+ <sect2>
+ <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>
-127.0.0.1 localhost.localdomain localhost (seen on debian)
-127.0.0.1 linux localhost (seen on Suse)
+ cd build
+ ant create-custom-property-file
</programlisting>
</informalexample>
- <simpara>If you see similar entries, revert the order so that "localhost" appears first:</simpara>
+ <simpara>But definitely the safest way to proceed is simply rebuilding everything:</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)
+ ant clean
+ ant
</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>
+ </sect2>
+ <sect2>
+ <title>Build database</title>
+ <warning>
+ <simpara>ONLY IF YOU'RE NOT MIGRATING AN EXISTING INSTANCE OF SCARAB !!</simpara>
+ </warning>
+ <sect3>
+ <title>Default database</title>
+ <simpara>Run the following command to build Scarab's deafult database including all default and seed data:</simpara>
<informalexample>
<programlisting>
-grant all on *.* to root@localhost identified by 'secret';
+ ant create-db
</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>
+ </sect3>
+ <sect3>
+ <title>JIRA templates</title>
+ <simpara>
+ By default, a module is created with issue-types that match the
+ structure of JIRA, enabling transfer of issues from JIRA to Scarab.
+ If you don't want this extra module in your issue tracker, then you
+ can pass the option "-Dskip.jira.templates.data=true" to ant, e.g.:
+ </simpara>
<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;
+ ant create-db -Dskip.jira.templates.data=true
</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>
+ <simpara>This option is independent of 'skip.seed.data' or 'skip.default.data' (see next chapter), so they can be specified together.</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>
+ </sect3>
+ <sect3>
+ <title>Seed data</title>
+ <simpara>
+ By default, some seed data are put into Scarab's database. There are
+ some modules and already entered issues. To avoid this,
+ you can pass the option "-Dskip.seed.data=true" to ant. To skip all
+ default global data, too, as there are some attributes, issue-types and so on,
+ you can additionally pass the option "-Dskip.default.data=true" to ant:
+ </simpara>
<informalexample>
<programlisting>
-mysqladmin -u admin -h localhost -p create scarab
-Enter password: ******
+ ant create-db -Dskip.seed.data=true -Dskip.default.data=true
</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>
+ <simpara>This options are independent of 'skip.jira.templates.data', so they can be specified together.</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>
+ </sect3>
+ </sect2>
+ <sect2>
<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>
+ <sect3>
<title>Last resort (applies to some linux distros)</title>
<para>
If nothing helps, check this (thanks to Josh Howe for investigation).
@@ -519,77 +513,43 @@
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 <c
omputeroutput>VARBINARY = VARCHAR2(4000)</computeroutput> -- that is a slightly more persistent modification.</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>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Start inbuilt Tomcat</title>
+ <simpara>If you haven't chosen to deploy Scarab, as a WAR file or else, into an external servlet container, then you
+ are able to run the compiled Scarab sources by an inbuilt Tomcat distribution.</simpara>
+ <simpara>On Windows, double-click on the file <computeroutput>$SCARAB_HOME/tomcat/bin/startup.bat</computeroutput></simpara>
+ <simpara>On Unix/Linux, run the following shell script: <computeroutput>$SCARAB_HOME/tomcat/bin/startup.sh</computeroutput></simpara>
+ <simpara>The webapplication will be available as reflected by the settings of the following properties:</simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>scarab.http.scheme</simpara>
+ </listitem>
+ <listitem>
+ <simpara>scarab.http.domain</simpara>
+ </listitem>
+ <listitem>
+ <simpara>scarab.http.port</simpara>
+ </listitem>
+ <listitem>
+ <simpara>scarab.context</simpara>
+ </listitem>
+ </itemizedlist>
+ <simpara>In general your Scarab will be available from a browser on the URL: ${scarab.http.scheme}://${scarab.http.domain}:${scarab.http.port}/${scarab.context}</simpara>
+ <simpara>Consequently in case you did NOT change the default properties, you now will find Scarab by pointing your Browser to: http://localhost:8080/scarab</simpara>
+ <simpara>
+ If your setup is ok, you will be presented with the Scarab login page after
+ one initial redirect. If that happens, congratulations! You now have Scarab
+ installed and running on your system.
+ </simpara>
+ <simpara>
+ If any of the above steps fail, then please read the full README.txt file.
+ If you are still having problems then please subscribe to the Scarab users
+ mailing list at: [email protected]</simpara>
+ <simpara>Once you are subscribed, send a message to [email protected] detailing your problem.</simpara>
+ </sect1>
<sect1>
<title>Building Scarab with the web install application</title>
<simpara>For a quick install, a test install or if you just want to experiment with Scarab, you will find the web installation simpler and much more user-friendly. This simplified process allows you to define the most current parameters and gives you short explanations and even some advice.</simpara>
@@ -653,153 +613,4 @@
<simpara>You may now restart Tomcat as has been explained in the Step 3 above.</simpara>
</sect2>
</sect1>
- <sect1>
- <title>Building Scarab: command-line installation</title>
- <note>
- <simpara>This section is a formatted copy of the INSTALL file at the root of the Scarab distribution.</simpara>
- </note>
- <sect2>
- <title>Step 1: Unpack the Scarab distribution</title>
- <para>
- The Scarab release can be downloaded as either a .zip or a .tar.gz file.
- Unpack either one of these into a directory that you have write access
- to.
- </para>
- </sect2>
- <sect2>
- <title>Step 2: Migrating an old (pre b19) version of Scarab</title>
- <para>Please, read the 2.1 section of the MIGRATION file for instructions on the migration of your current settings.</para>
- <para>If you don't have an existing pre-b19 Scarab installation, or you don't want to keep your old settings and data, then you can skip this step.</para>
- </sect2>
- <sect2>
- <title>Step 3: Configure Scarab</title>
- <para>
- If you already have an old build.properties file from a previous version
- of Scarab, please copy this build.properties file to the $SCARAB_ROOT
- directory (NOT the build directory) of your new installation.
- </para>
- <para>If you don't already have an old build.properties file, create one as follows:</para>
- <orderedlist>
- <listitem>
- <simpara>Go to your $SCARAB_HOME directory</simpara>
- </listitem>
- <listitem>
- <simpara>copy (not rename!) one of the following two files to build.properties:</simpara>
- <simpara>project.properties (full customization property set)</simpara>
- <simpara>minimal.properties (minimal customization property set)</simpara>
- <simpara>
- You will choose project.properties as your starting point, if you
- are a developer who is deeply involved into the Scarab development.
- 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>
- </listitem>
- <listitem>
- <simpara>
- Scroll through your build.properties and be sure to follow the notes.
- If you really miss a property which is not yet available in your
- build.properties just add it to your build.properties!
- </simpara>
- </listitem>
- </orderedlist>
- </sect2>
- <sect2>
- <title>Step 4: Build Scarab</title>
- <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>
- <warning>
- <simpara>ONLY IF YOU'RE NOT MIGRATING AN EXISTING INSTANCE OF SCARAB !!</simpara>
- <simpara>Read the 'MIGRATION' file if you need to preserve your data !!</simpara>
- </warning>
- <simpara>Now you can create and populate the Scarab database. </simpara>
- <simpara>Just run one of the commands bellow:</simpara>
- <simpara>If you are using ant:</simpara>
- <simpara>ant create-db</simpara>
- <simpara>or</simpara>
- <simpara>ant -Dskip.seed.data=true create-db</simpara>
- <simpara>
- The second command avoids the population of your database with the
- Scarab sample data. If you are just testing Scarab out, then we
- recommend that you use the first option and load the sample data
- into the database.
- </simpara>
- <simpara>If you are using maven, similar commands exist:</simpara>
- <simpara>maven scarab:create-db</simpara>
- <simpara>maven -Dskip.seed.data=true scarab:create-db</simpara>
- <sect3>
- <title>JIRA templates</title>
- <simpara>
- By default, a module is created with issue-types that match the
- structure of JIRA, enabling transfer of issues from JIRA to Scarab.
- If you don't want this extra module in your issue tracker, then you
- 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>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>
- </sect3>
- </sect2>
- <sect2>
- <title>Step 5b: Migrate your current data</title>
- <note>
- <simpara>ONLY IF YOU ARE MIGRATING AN EXISTING INSTANCE OF SCARAB !!</simpara>
- </note>
- <simpara>Go to MIGRATION file for instructions on migrating your existing data.</simpara>
- </sect2>
- <sect2>
- <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>
- <itemizedlist>
- <listitem>
- <simpara>scarab.http.scheme</simpara>
- </listitem>
- <listitem>
- <simpara>scarab.http.domain</simpara>
- </listitem>
- <listitem>
- <simpara>scarab.http.port</simpara>
- </listitem>
- <listitem>
- <simpara>scarab.context</simpara>
- </listitem>
- </itemizedlist>
- <simpara>In general your Scarab will be available from a browser on the URL: ${scarab.http.scheme}://${scarab.http.domain}:${scarab.htp.port}/${scarab.context}</simpara>
- <simpara>Consequently in case you did NOT change the default properties, you now will find Scarab by pointing your Browser to: http://localhost:8080/scarab</simpara>
- <simpara>
- If your setup is ok, you will be presented with the Scarab login page after
- one initial redirect. If that happens, congratulations! You now have Scarab
- installed and running on your system.
- </simpara>
- <simpara>
- If any of the above steps fail, then please read the full README.txt file.
- If you are still having problems then please subscribe to the Scarab users
- mailing list at: [email protected]</simpara>
- <simpara>Once you are subscribed, send a message to [email protected] detailing your problem.</simpara>
- </sect2>
- </sect1>
</chapter>
Removed: branches/release/0.22/www/book/install-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/install-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/integration-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/integration-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/intro-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/intro-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/issues-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/issues-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/login-de.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/login-de.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/login-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/login-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/maven-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/maven-fr.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/www/book/modules-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/modules-en.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/www/book/modules-en.xml (original)
+++ branches/release/0.22/www/book/modules-en.xml 2010-02-03 04:12:05-0800
@@ -3,7 +3,7 @@
<title>Creating and managing modules</title>
<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>
+ <simpara>From the home page, choose any module, if you have not done that already. The creation of a new module cannot occur outside a context.</simpara>
<screenshot>
<graphic fileref="images/module-creation0.png"/>
</screenshot>
@@ -14,7 +14,7 @@
<screenshot>
<graphic fileref="images/module-creation1b.png"/>
</screenshot>
- <simpara>From there, choose Modules, Manage modules and push the Create new button.</simpara>
+ <simpara>From there, choose Global Data, Manage modules and push the Create new button.</simpara>
<screenshot>
<graphic fileref="images/module-creation2.png"/>
</screenshot>
Removed: branches/release/0.22/www/book/modules-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/modules-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/netbeans-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/netbeans-fr.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/www/book/queries-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/queries-en.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/www/book/queries-en.xml (original)
+++ branches/release/0.22/www/book/queries-en.xml 2010-02-03 04:12:05-0800
@@ -60,11 +60,11 @@
<sect1>
<!-- Source: UserQueryAdvanced section of the online help -->
<title>Advanced queries</title>
- <para>The advanced query form provides an interface for you to unambiguously define your search criteria. You can use this form to enter values for some, all or none of the attributes available in your issue type. You can further qualify your search criteria by requesting issues within a particular number range or date range. Say you want to know all closed issues relating to the AIX operating system within the last week. You can enter a date range (use the MM/DD/YYYY format, for instance, 01/01/2002) and define specific values for the operating system and status attributes. Click option from the Select query list on the query bar. Clicking the Submit button will run the query.</para>
+ <para>The advanced query form provides an interface for you to unambiguously define your search criteria. You can use this form to enter values for some, all or none of the attributes available in your issue type. You can further qualify your search criteria by requesting issues within a particular number range or date range. Say you want to know all closed issues relating to the AIX operating system within the last week. You can enter a date range (use the given format) and define specific values for the operating system and status attributes. Click option from the Select query list on the query bar. Clicking the Submit button will run the query.</para>
<para>You can define values for some, none or all of the attributes. Scarab will search the knowledge base for issues that contain all of the values you have specified. The advanced query form allows you to define fine grained search criteria. There are three types of search criteria available on the advanced query form:</para>
<itemizedlist>
<listitem>
- <para>Search the knowledge base</para>
+ <para>Search by attribute</para>
</listitem>
<listitem>
<para>Searching by personnel</para>
@@ -75,9 +75,9 @@
</itemizedlist>
<para>You can use each of these sections individually or a combination to qualify your searches. If you run a query without defining any attributes all issues associated with the logged in user ID will be returned. </para>
<sect2>
- <title>Search the knowledge base</title>
- <para>The <emphasis role="bold">Search the knowledge base</emphasis>. section provides a space for you to define values for issue attributes. Each attribute that is available to your issue type is represented here. You can define values for all, some or none of the issue attributes. You can also limit your search to a range of issues or creation dates. .</para>
- <para>Once the issue is submitted, the database will be searched for issues containing the values for all of the attributes defined in your search criteria. To effectively find the issues you are most interested in you want to define only the attributes that will meet your criteria. If you define attributes outside of your requirements you will be less likely to find any issues that meet your criteria. For instance, jdoe is looking for issues involving database errors affecting one of the UNIX operating systems. Rather than defining a value for the operating system, jdoe can create a search that will search for text strings about the database errors. If jdoe needs to refine the search criteria further, other attributes can be defined. When defining your search criteria, you should star
t with the smallest set of characteristics relevant to your needs.</para>
+ <title>Search by attribute</title>
+ <para>The first section provides a space for you to define values for issue attributes. Each attribute that is available to your issue type is represented here. You can define values for all, some or none of the issue attributes. You can also limit your search to a range of issues or creation dates.</para>
+ <para>Once the values are submitted, the database will be searched for issues containing the values for all of the attributes defined in your search criteria. To effectively find the issues you are most interested in you want to define only the attributes that will meet your criteria. If you define attributes outside of your requirements you will be less likely to find any issues that meet your criteria. For instance, jdoe is looking for issues involving database errors affecting one of the UNIX operating systems. Rather than defining a value for the operating system, jdoe can create a search that will search for text strings about the database errors. If jdoe needs to refine the search criteria further, other attributes can be defined. When defining your search criteria, you should st
art with the smallest set of characteristics relevant to your needs.</para>
</sect2>
<sect2>
<title>Searching by personnel</title>
Removed: branches/release/0.22/www/book/queries-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/queries-fr.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/www/book/reports-en.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/reports-en.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/www/book/reports-en.xml (original)
+++ branches/release/0.22/www/book/reports-en.xml 2010-02-03 04:12:05-0800
@@ -15,10 +15,10 @@
<simpara>Select the report you wish to run by clicking on the report name, or access the report builder by clicking the <emphasis role="bold">Create new</emphasis> button.</simpara>
</listitem>
</itemizedlist>
- <para>The Scarab report build consists of three tabs: The <emphasis role="bold">Report information</emphasis> tab allows you to define the scope of the report and enter summary information. The summary information is for saving reports. There are two sections on this tab: <emphasis role="bold">Artifact types selected for this report</emphasis>, and <emphasis role="bold">Summary</emphasis>. </para>
+ <para>The Scarab report build consists of several steps. At first you have to select the issue types.</para>
<sect1>
<title>Selecting issue types</title>
- <para>The issue type included in the report defaults to the currently selected issue type. If you wish to define a report for a different or multiple issue types/modules, click the <emphasis role="bold">Edit list</emphasis> button. This will take you to the <emphasis role="bold">Cross module/issue type list</emphasis> page. You can use this page to define a list of issues types within the current module or across multiple modules to be included in your report. It is highly recommended that the issue types for the report be chosen prior to working with the content tabs. Though it is possible to modify the list later, additions that conflict with already entered data on the other tabs will not be allowed.</para>
+ <para>The issue type included in the report defaults to the currently selected issue type. If you wish to define a report for a different or multiple issue types/modules, click the link for the <emphasis role="bold">List Editor</emphasis>. This will take you to the <emphasis role="bold">Cross module/issue type list</emphasis> page. You can use this page to define a list of issues types within the current module or across multiple modules to be included in your report. It is necessary that the issue types for the report be chosen prior to working with the content tabs. Though it is possible to modify the list later, additions that conflict with already entered data on the other tabs will not be allowed.</para>
<para>On the <emphasis role="bold">Cross module/issue type list</emphasis> page, you can perform the following tasks:</para>
<itemizedlist>
<listitem>
@@ -64,21 +64,21 @@
<title>
<emphasis role="bold">Data types</emphasis>
</title>
- <para> The <emphasis role="bold">Row/Column criteria</emphasis> section allows you to select the type of data presented in the rows or columns of your report. The available selections are:</para>
+ <para>The <emphasis role="bold">Row/Column criteria</emphasis> section allows you to select the type of data presented in the rows or columns of your report. The available selections are:</para>
<itemizedlist>
<listitem>
<para>
- <emphasis role="bold">Attribut(s) / option(s)</emphasis> When this data type is selected, you can choose from among the attributes and options defined for the selected issue types.</para>
+ <emphasis role="bold">Attribute(s) / Option(s)</emphasis> When this data type is selected, you can choose from among the attributes and options defined for the selected issue types.</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">Utilisateurs (par attribut utilisateur)</emphasis>When this data type is selected, you can choose from among the module members and specify a user attribute for each user selected.</para>
+ <emphasis role="bold">Users (for user attributes)</emphasis> When this data type is selected, you can choose from among the module members and specify a user attribute for each user selected.</para>
</listitem>
<listitem>
- <para>Date(s)<emphasis role="bold"/> When this data type is selected, you can define dates for each row or column of your report.</para>
+ <para><emphasis role="bold">Date(s) / Date Range(s)</emphasis> When this data type is selected, you can define dates for each row or column of your report.</para>
</listitem>
</itemizedlist>
- <para>The option selected in the <emphasis role="bold">Select content type</emphasis> field determines the data available in the rest of the sections of these tabs. Only one content type can be used for each heading. If you choose Date(s) as a content type on either the <emphasis role="bold">Row content</emphasis> or <emphasis role="bold">Column content</emphasis> tab, it must be the only heading on that axis. However, you can define user criteria for one or more heading levels and option attributes for other headings on the same axis. Changing the content type to Date(s) after defining a set of user or attribute/option criteria for either the row or column content tabs will discard the previously entered data for that tab.</para>
+ <para>The option selected in the <emphasis role="bold">Select content type</emphasis> field determines the data available in the rest of the sections of these tabs. Only one content type can be used for each heading. If you choose Date(s) / Date Range(s) as a content type on either the <emphasis role="bold">Row content</emphasis> or <emphasis role="bold">Column content</emphasis> tab, it must be the only content type on that axis. However, you can define different criteria for one or more heading levels on the same axis. Changing the content type after defining a set for either the row or column content tabs will discard the previously entered data for that tab.</para>
</sect2>
<sect2>
<title>
@@ -121,7 +121,7 @@
<para>You must have defined at least one heading containing <emphasis role="bold">Attribute/option(s)</emphasis> in your report before you can define groups. To group options within headings:</para>
<orderedlist>
<listitem>
- <para>DOn the <emphasis role="bold">Row content</emphasis> tab or the <emphasis role="bold">Column content</emphasis> tab, select a heading containing the <emphasis role="bold">Attribute/option(s)</emphasis> content type and click the <emphasis role="bold">Edit selected heading</emphasis> button.</para>
+ <para>On the <emphasis role="bold">Row content</emphasis> tab or the <emphasis role="bold">Column content</emphasis> tab, select a heading containing the <emphasis role="bold">Attribute/option(s)</emphasis> content type and click the <emphasis role="bold">Edit selected heading</emphasis> button.</para>
</listitem>
<listitem>
<para>In the group related data section, enter a name for the group and click the <emphasis role="bold">Add new</emphasis> button. Repeat this step if you wish to have additional groups within this heading.</para>
@@ -158,13 +158,13 @@
<para>To create date/time reports:</para>
<orderedlist>
<listitem>
- <para>On either the <emphasis role="bold">Row content</emphasis> or <emphasis role="bold">Column content</emphasis> tab, Select <emphasis role="bold">Date(s) </emphasis>from the <emphasis role="bold">Select content type</emphasis> drop down box.</para>
+ <para>On either the <emphasis role="bold">Row content</emphasis> or <emphasis role="bold">Column content</emphasis> tab, Select <emphasis role="bold">Date(s) / Date Range(s)</emphasis> from the <emphasis role="bold">Select content type</emphasis> drop down box.</para>
</listitem>
<listitem>
- <para>In the <emphasis role="bold">Select row/column (dates) content</emphasis> table, use the drop down boxes to select the date and time you want to include in your report.</para>
+ <para>In the <emphasis role="bold">Select row/column (dates) content</emphasis> table, use the calendar to select the date and time you want to include in your report.</para>
</listitem>
<listitem>
- <para>Click the <emphasis role="bold">Add single date/time</emphasis> button.</para>
+ <para>Click the <emphasis role="bold">Add</emphasis> button.</para>
</listitem>
<listitem>
<para>Continue adding dates in this fashion until all desired dates are included.</para>
Removed: branches/release/0.22/www/book/reports-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/reports-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/scarab-admin-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/scarab-admin-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/scarab-dev-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/scarab-dev-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/scarab-user-de.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/scarab-user-de.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/scarab-user-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/scarab-user-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/schema-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/schema-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/subversion-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/subversion-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/superadmin-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/superadmin-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/workflow1-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/workflow1-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/workflow2-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/workflow2-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/xml-import-export-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/xml-import-export-fr.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/www/book/xml-rpc-fr.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/www/book/xml-rpc-fr.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/xdocs/databases/database_independence.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/databases/database_independence.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/databases/database_independence.xml (original)
+++ branches/release/0.22/xdocs/databases/database_independence.xml 2010-02-03 04:12:05-0800
@@ -37,43 +37,6 @@
SELECT 1 FROM DUAL
</pre>
</p>
-<p>
-
-<h5>Database Configuration</h5>
-</p>
-<p>
-The following properties in <code>build.properties</code>
-can be used to select and customize the database.
-<ul>
-<li>
-<code>scarab.database.type</code>
-</li>
-</ul>
-</p>
-<p>
-
-
-<h5>Data Load Configuration</h5>
-</p>
-<p>
-The following properties in <code>build.properties</code>
-can be used to customize the database load.
-<ul>
-<li>
-<code>scarab.database.loadorder</code>
-</li>
-<li>
-<code>scarab.database.validationQuery</code>
-</li>
-<li>
-<code>skip.seed.data</code>
-</li>
-<li>
-<code>seed.data.sql</code>
-</li>
-</ul>
-</p>
-
</section>
</body>
</document>
\ No newline at end of file
Modified: branches/release/0.22/xdocs/databases/hypersonic.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/databases/hypersonic.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/databases/hypersonic.xml (original)
+++ branches/release/0.22/xdocs/databases/hypersonic.xml 2010-02-03 04:12:05-0800
@@ -2,77 +2,35 @@
<document>
<properties>
<title>Scarab - Hypersonic</title>
-<author email="[email protected]">Eric Pugh</author>
-<author email="Jason.Gillam NO SPAM vignette.com">Gillam, Jason</author>
+<author email="[email protected]">Johannes Hoechstaedter</author>
</properties>
<body>
<section name="Hypersonic">
<p>
-1 - set property: scarab.database.type=hypersonic (note - this will generate
-the scripts but the current ant script won't automatically install the
-database schema for a hypersonic db. You'll have to manually load them.)
+I did some short tests only, using Scarab with a Hypersonic database in file mode and
+very basic settings, but it worked right from the start.
</p>
-
-
-<p>
-2 - set other DB properties to point to your hypersonic DB. You need to run in server mode
-</p>
-
-<p>
-4 - Torque has a bug when generating hypersonic scripts. The only script in
-scarab which exposes the problem is the scarab.sql file. You will have to
-manually go in there and look for an extra comma at the end of each table
-column definition in the CREATE statements. Some of them have the extra
-comma (which needs to be deleted), and others are okay.
-</p>
-
-
-
<p>
-6 - Use one of the hypersonic tools (DatabaseManager works well) to open and
-execute each of the .sql scripts in the same order that they appear in the
-create-mysql-database.bat/.sh file.
+Everything you will need for a very basic installation, is already included into Scarab.
</p>
-
<p>
----
-Outstanding Issues:
+Set property for database type:
+<source>scarab.database.type=hypersonic</source>
</p>
-
<p>
-Just this one. The scarab web application appears to be working, including
-the e-mail registration part. I'm stuck at a spot where I don't seem to be
-authorized to do anything (not even the admin account is). So I can't add
-modules or even see any issues in the sample application. Whether this is a
-problem with Scarab or a problem with hypersonic has yet to be determined.
-Nothing showed up in the application server logs.
+Set all other necessary DB properties to point to your hypersonic DB, e.g.:
+<source>
+scarab.database.url=jdbc:hsqldb:file:/C:/test
+scarab.database.admin.username=SA
+scarab.database.admin.password=
+scarab.database.username=SA
+scarab.database.password=
+</source>
</p>
-
<p>
-If anyone figures this out, please post a response. Hypersonic makes an
-excellent platform for small deployments because it's opensource and you
-don't have to run a full database in a separate process (i.e. standalone
-"file" mode).
+Then run <source>ant create-db</source> and it should work.
</p>
-
-
-
-<h4>Basic instructions</h4>
-Torque generates the sql properly except for a couple modifications. After run ant create-db go
-into /target/scarab/web-inf/sql/hypersonic and do these changes:
-<ol>
-<li> Change all # to --</li>
-
-<li> Change all drops from "drop table if exists TURBINE_USER_GROUP_ROLE;" to
-"drop table TURBINE_USER_GROUP_ROLE is exists"</li>
-
-<li>change mediumblob to object</li>
-
-<li> change mediumtext to varchar</li>
-</ol>
-
-Then rerun the ant create-db and it'll work.
</section>
</body>
</document>
\ No newline at end of file
Modified: branches/release/0.22/xdocs/databases/index.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/databases/index.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/databases/index.xml (original)
+++ branches/release/0.22/xdocs/databases/index.xml 2010-02-03 04:12:05-0800
@@ -33,7 +33,7 @@
</tr>
<tr>
<td><a href="postgresql.html">PostgreSQL</a></td>
- <td><font color="orange"><b>Full</b></font></td>
+ <td><font color="green"><b>Full</b></font></td>
<td>
<a href="mailto:[email protected]">jorgeuriarte</a>
<br/><a href="[email protected]">ptillemans</a>
@@ -52,13 +52,14 @@
</tr>
<tr>
- <td><a href="hypersonic.html">HSQLDB (was: Hypersonic SQL)</a></td>
- <td><font color="red"><b>No</b></font></td>
+ <td><a href="hypersonic.html">HSQLDB</a></td>
+ <td><font color="orange"><b>Partial</b></font></td>
<td>
<a href="mailto:[email protected]">hdabbous</a>
<br/><a href="[email protected]">ptillemans</a>
+ <br/><a href="mailto:[email protected]">jhoech</a>
</td>
- <td>Integrated, but SQL-errors. Support deferred after release 1.0</td>
+ <td>Working, but not fully tested. Further help needed from the community to certify it works perfectly.</td>
</tr>
<tr>
Modified: branches/release/0.22/xdocs/databases/scarabdb.png
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/databases/scarabdb.png?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
Binary files. No diff available.
Added: branches/release/0.22/xdocs/faq.fml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/faq.fml?view=markup&pathrev=10887
==============================================================================
--- (empty file)
+++ branches/release/0.22/xdocs/faq.fml 2010-02-03 04:12:05-0800
@@ -0,0 +1,736 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<faqs title="Frequently Asked Questions">
+
+ <part id="general">
+ <title>General</title>
+ <faq id="0">
+
+ <question><b>
+ How can I not load the Sample Data?
+ </b></question>
+ <answer>
+Remind the additional build properties, such as <code>skip.seed.data</code> for example.
+ </answer>
+ </faq>
+ <faq id="1">
+
+ <question><b>
+ Is there suitable 'propaganda' material that I could use to convince my boss to use Scarab?
+ </b></question>
+ <answer>
+The website and use of Scarab itself are all we currently have.
+Scarab is very easy to install and setup,
+so it should not take you much time to become comfortable with
+Scarab so that you can perform your own demonstration.
+ </answer>
+ </faq>
+ <faq id="2">
+ <question><b>
+ Is Scarab ready for production use?
+ </b></question>
+ <answer>
+Scarab is in pre-1.0 beta. It has been in development for several
+years now and there are quite a lot of features in it. On
+July 9th, 2002, we became self hosting. This means that we now
+use Scarab to track Scarab so we feel it is ready enough for
+usage. We also know that there are several large corporations
+using Scarab. Please note that we do not promise anything. If
+Scarab eats your database, then we hope you have good backups.
+ </answer>
+ </faq>
+ <faq id="3">
+ <question><b>
+ What are Scarab's disadvantages over Bugzilla?
+ </b></question>
+ <answer>
+<p>
+Scarab has many features and advantages over Bugzilla, which we
+are not going to get into here, but the primary disadvantages are:
+</p>
+
+<p>
+#1. Simple implementation of workflow<br />
+ Scarab default workflow implementation is simple, and does
+ not try to provide a full-blown Workflow engine.
+ This means that Scarab does not have any logic
+ implemented within it that allows you to say things
+ like: when the State is changed to closed, change the
+ resolution to resolved. There is an API for allowing
+ this to happen, and you can ask in the mailing lists for the
+ experiences of Scarab's users successfully implementing it.
+</p>
+
+<p>
+#2. testing and deployment as wide as Bugzilla<br />
+ Bugzilla has been deployed far and wide over a number
+ of years and has undergone a great amount of testing
+ and visibility on the Mozilla.org website. Scarab has
+ not had the same level of testing and usage.
+</p>
+ </answer>
+ </faq>
+ <faq id="4">
+ <question><b>
+ What problems might arise if I deploy Scarab now?
+ </b></question>
+ <answer>
+<p>
+We have not heard of any major data integrity issues. In other words, we
+have not heard of Scarab destroying its own database. However, we have
+found several bugs along the way where things were not being logged
+properly or other such annoyances.
+</p>
+
+<p>
+We recommend strongly that you make regular backups of your database by
+doing full dumps. That way, if something does go wrong, not only can you
+send us a copy of your database (if appropriate) but you can also revert
+to the previous state.
+</p>
+
+<p>
+We provide database upgrade scripts for each revision of Scarab. That
+way you can be sure that if you start using Scarab now, you will be able
+to forward migrate your data when there are Scarab updates. Please see
+the upgrade instructions below for more information.
+</p>
+
+<p>
+You may also run into various bugs or missing features within Scarab. It
+is best to first search our <a href="http://www.solitone.org/scarab/issues">issue database</a>
+to see if we know about the issue. If not, please let us know by reporting
+it to the issue tracker. If this does not help you, feel free, to send your
+complain to the mailing lists.
+</p>
+
+<p>
+Remember, Scarab is still pre-1.0 beta software and is still under
+heavy development.
+</p>
+ </answer>
+ </faq>
+ <faq id="5">
+ <question><b>
+ What documentation is available?
+ </b></question>
+ <answer>
+<p>
+Checkout this site.
+</p>
+ </answer>
+ </faq>
+ <faq id="6">
+ <question><b>
+ Why am I getting an error connecting to MySQL?
+ </b></question>
+ <answer>
+<p>
+From the, not longer exsiting, README.txt file:
+</p>
+
+<p>
+NOTE: If you get a 'Server configuration denies access to data source'
+ or 'access denied' or 'Invalid authorization' or
+ 'java.lang.NullPointerException: Connection object was null.'
+ error from MySQL in the log files, please read the MySQL
+ documentation on how to fix this error. We will not provide
+ support for this since it is really a MySQL configuration issue.
+</p>
+
+<p>
+ Hint: On some operating systems, there seems to be a weird
+ interation between the JVM, DNS resolution and the MySQL driver
+ where a JDBC url pointing to 'localhost' will resolve as
+ 'localhost.localdomain' and will prevent the connection to MySQL
+ from authenticating correctly because most people configure MySQL
+ for 'localhost'. One way to get around this is to use IP addresses
+ in both the MySQL ACL as well as in the JDBC url.
+</p>
+<p>
+ At least one person has reported that using '127.0.0.1' instead of 'localhost'
+ resolved a 'Server configuration denies access to data source' connection issue.
+</p>
+<p>
+ In order to set up the right permissions in MySQL, you may wish to
+ try executing this command on a Unix command line (it has been
+ reported to work for one person):
+</p>
+
+<p>
+ echo "GRANT ALL ON scarab.* to ''@localhost" | mysql mysql
+</p>
+
+<p>
+NOTE: Sometimes it may be useful to use "ant create-db" rather than any script
+ to diagnose connection issues since ant uses jdbc and the same URL
+ that Scarab does while running.
+
+</p>
+
+<p>
+ Here is a link to also help you solve the permissions
+ problem:
+</p>
+
+<p>
+ <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Access_denied">MySQL documentation</a>
+</p>
+ </answer>
+ </faq>
+ <faq id="7">
+ <question><b>
+ How can I contribute to Scarab and why?
+ </b></question>
+ <answer>
+<p>
+How: Login into a mailinglist and let us know.
+</p>
+
+<p>
+Why: A first class issue tracking system as Scarab that
+is open source, needs developers.
+</p>
+ </answer>
+ </faq>
+ <faq id="8">
+ <question><b>
+ How do I hook Scarab up to (or behind) Apache?
+ </b></question>
+ <answer>
+<p>
+Look into the documentation files of Scarab and Apache Webserver.
+If this does not help you, here is a configuration for the not longer
+existing "Scarab Live Server" from scarab.collab.net:
+</p>
+
+<pre>
+NameVirtualHost 157.22.245.3
+<VirtualHost 157.22.245.3>
+ ServerName scarab.collab.net
+ RewriteEngine on
+ RewriteRule /(.+) http://scarab.collab.net:8081/$1 [P]
+ ProxyPassReverse / http://scarab.collab.net:8081/s/
+</VirtualHost>
+</pre>
+
+<p>
+This is pretty historic. The author mentioned:
+"The above might not be optimal or even correct, but it works for
+me. You will need to have mod_rewrite and mod_proxy enabled on your
+server. A 'faster' method of doing the same thing would be to use
+Tomcat's mod_jk/mod_webapp with some rewrite rules (to get the short
+url's), but I'm not doing that, so I don't have configuration to show
+for it. Contributions welcome."
+</p>
+<p>
+For hiding Scarab behind Apache SSL, a similar setup as above would
+work, you would just want to make sure to listen to the https port 443
+in the VirtualHost declaration.
+</p>
+ </answer>
+ </faq>
+ <faq id="9">
+ <question><b>
+ How do I populate the database with my own issue types, attributes
+and attribute options?
+ </b></question>
+ <answer>
+<p>
+When you first install Scarab, not using the default data for database,
+you will get an empty database that is only populated with the
+required data. Therefore, you will need to set up your installation
+with new Modules, Issue types, Attributes and Attribute options.
+</p>
+
+<p>
+Create all items in global data first, apply them to your modules afterwards.
+</p>
+ </answer>
+ </faq>
+ <faq id="10">
+ <question><b>
+ How do I set up Scarab so that it will send a copy of each issue
+change to a particular email address (ie: a mailing list or the project leader)?
+ </b></question>
+ <answer>
+As either the module administrator or the domain administrator user, go
+to the Admin->Modules->Manage modules screen and edit the particular
+module that you are interested in tracking issue changes in. Set the
+'Archive email' address to the email address that you want. If you want
+this email to go to multiple people, set up a mailing list and subscribe
+the people to that mailing list and then set the 'Archive email' address
+to be the address of the mailing list.
+ </answer>
+ </faq>
+ <faq id="11">
+ <question><b>
+ When I receive notification email from scarab, the url to the
+ issue starts with http://localhost:8080/. Clearly that is bad because I
+ want the email to point to the server that Scarab is on. How to I make
+it say the server domain name instead?
+ </b></question>
+ <answer>
+You have one fewer thing to configure. For example, look at Scarab's properties.
+ </answer>
+ </faq>
+ <faq id="12">
+ <question><b>
+ How can I set defaults for the various attributes on
+issue entry?
+ </b></question>
+ <answer>
+Right now, that is what issue templates or workflow defintions can do.
+ </answer>
+ </faq>
+ <faq id="13">
+ <question><b>
+ What is the process for upgrading Scarab?
+ </b></question>
+ <answer>
+<p>
+The Scarab developers provide database upgrade scripts
+for each new version of Scarab. These scripts reside in the scarab/src/sql/upgrade directory.
+Some of these scripts are .sql files and some might be unix shell .sh files.
+</p>
+
+<p>
+To execute the .sql scripts you should type something along the lines
+of:
+</p>
+
+<p>
+mysql DATABASE_NAME < mysql-upgrade-1.0b8-1.0b9-1.sql
+</p>
+
+<p>
+To execute the .sh scripts you should type something along the lines
+of:
+</p>
+
+<p>
+./mysql-upgrade-1.0b8-1.0b9-3.sh --password
+</p>
+
+<p>
+Note that you will need to execute ALL of the scripts in order of
+upgrade version number and script order. For example, if you are
+upgrading from 1.0b8 to 1.0b9, then you should execute
+mysql*b8*b9-1.sql, mysql*b8*b9-2.sql, etc. Also note that the --password
+argument to the shell script is optional and not required if you do not
+need to specify a password.
+</p>
+
+<p>
+If you have deployed Scarab with the default settings and are running
+out of the default target directory, then you should download the new
+version of Scarab, move the target directory into the new version of
+Scarab, cd into target/webapps/scarab/WEB-INF and backup and remove the
+following directories: classes, conf, lib, sql, src. You should be
+careful to not remove the indexes and attachments directories (if they
+exist). Once you have done that, you can build Scarab again. You should
+take note to create a ~/build.properties file which stores your changes
+to the Scarab settings so that when you build again, your settings remain intact.
+</p>
+ </answer>
+ </faq>
+ <faq id="14">
+ <question><b>
+ I tried to register for Scarab's issue tracker and got the following error:
+ </b></question>
+ <answer>
+Alert! Sorry, the email you submitted (EMAIL) does not have a DNS A or MX record
+defined. It is likely that the domain is invalid and that we cannot send
+you email. Please see ftp://ftp.isi.edu/in-notes/rfc2505.txt for more
+details. Please try another email address or contact your system
+administrator.
+<p>
+Scarab has an optional feature which is enabled by setting the
+scarab.register.email.checkRFC2505=true property in your
+build.properties. This feature uses DNS to check that the domain which
+is being registered has a valid A or MX record which is the minimum required
+to send email to a domain name. This feature is enabled
+to help try to prevent people from creating bogus accounts on the
+server.
+</p>
+
+<p>
+The fix is simple, create an A or MX record for your domain entry.
+</p>
+ </answer>
+ </faq>
+ <faq id="15">
+ <question><b>
+ Can I see Scarab in action without installing it myself?
+ </b></question>
+ <answer>
+<p>
+It's not a big deal to set up a small testing environment. Following the given build how to's.
+Once uppon a time, there was an instance for testing on:
+<a href="http://www.saxess.com/en/components/scarab/testserver.page">http://www.saxess.com/en/components/scarab/testserver.page</a>.<br/>
+This was intended to be a testing instance for the actual rebuilt of the HEAD, including all bugs and still incomplete features.<br/>
+Scarab also has the self-tracker availaible but please, don't use it for testing. It should be used only for reporting of Scarab's issues.
+</p>
+ </answer>
+ </faq>
+ <faq id="16">
+ <question><b>
+ I get a funny error when trying to run Scarab on Tomcat 4.1.x:
+ </b></question>
+ <answer>
+<pre>
+java.lang.VerifyError: (class:
+org/apache/fulcrum/intake/transform/XmlToAppData, method: parseFile
+signature:
+(Ljava/lang/String;Z)Lorg/apache/fulcrum/intake/xmlmodel/AppData;)
+Incompatible object argument for function call
+</pre>
+
+<p>
+Tomcat has several directories set up in order to create different
+'levels' of classpaths. There is a classpath that is specific to Tomcat
+and a classpath that is shared by all of the webapplications that Tomcat
+is running. Since Scarab still depends on Xerces 1.x, we need to make
+sure that that is the only Xerces available to Scarab at runtime.
+</p>
+
+<p>
+In order to make Scarab work with Tomcat 4.1.x, you will need to move
+the xercesImpl.jar from tomcat/common/endorsed to tomcat/server/lib.
+This makes it so that the Xerces 2.x that comes with Tomcat is only used
+by Tomcat. You will also need to make sure that if you have any other
+webapplications which depend on Xerces (1.x or 2.x), that they include a
+copy of the .jar file in their WEB-INF/lib directory.
+</p>
+
+<p>
+It is sad that this needs to be this way, but due to Xerces
+incompatibility issues, that is the way it is. Note that we will
+eventually make Scarab dependent on Xerces 2.x so that this is not an
+issue, but we are not quite there yet.
+</p>
+ </answer>
+ </faq>
+ <faq id="17">
+ <question><b>
+ I want Scarab to be deploed as a WAR.
+ </b></question>
+ <answer>
+<p>
+There are special build targets for this, e.g.:
+<code>ant war</code>
+</p>
+ </answer>
+ </faq>
+ <faq id="18">
+ <question><b>
+What is the best way to make duplicate installations of Scarab on multiple
+machines/databases? In other words, I want to have multiple installations
+of Scarab and I don't want to have to set up each one by hand.
+ </b></question>
+ <answer>
+<p>
+Right now, the easiest way is to set up one installation of Scarab, then
+mysqldump the database and import it into the other database.
+Eventually, we will have the ability to export/import the Scarab
+'settings'.
+</p>
+ </answer>
+ </faq>
+ <faq id="19">
+ <question><b>
+ I see a lot of little temp files created on disk.
+ </b></question>
+ <answer>
+<p>
+The reason for this is because when you upload a file attachment, the
+upload system also sends the form data. Because of this, each little bit
+of data will get a file created for it. You can adjust the size of the
+memory cache so that more of this data is held in temp memory (and not
+created as files) with this property:
+</p>
+
+<pre>
+# The maximum size of a request that will have it's elements cached in
+# memory by TurbineUploadService class.
+#
+services.UploadService.size.threshold=8192
+</pre>
+
+<p>
+These files should get cleaned up as the object is garbage collected, or
+the Java Virtual Machine is shutdown. If they persist after a shutdown,
+you can most likely safely remove them.
+</p>
+ </answer>
+ </faq>
+ <faq id="20">
+ <question><b>
+ Is there a way to turn off the auto-logoff feature or
+ extend the amount of time before it automatically
+invalidates a user and forces them to log in again?
+ </b></question>
+ <answer>
+<p>
+In your build.properties, define the following:
+</p>
+
+<pre>
+# This is the timeout in seconds for sessions. If the value is
+# left commented out, the servlet container's default timeout
+# will be left as is.
+session.timeout = 1800
+</pre>
+
+<p>
+If you want to disable logging people off, just set the value to
+a very high number.
+</p>
+ </answer>
+ </faq>
+ </part>
+
+<part id="xml">
+ <title>XML Import</title>
+
+ <faq id="21">
+ <question><b>
+ I need to add issues to scarab. How do I begin?
+ </b></question>
+ <answer>
+The best place to start is by studying an issue exported by scarab. First study
+how the issue sits in scarab, and then browse to
+<strong>Admin->Modules->XML export issues</strong> and export that issue.
+issue. Correlate UI w/ its representation in xml. Also study the comments
+in the <a
+href="http://scarab.tigris.org/source/browse/scarab/src/dtd/scarab.dtd?rev=1">scarab
+dtd</a> for clarification on scarab's interpretation of xml elements. Note
+that many elements have subtly different representations in the UI than they
+do in the dtd.
+ </answer>
+ </faq>
+<faq id="22">
+<question><b>
+ Can running an import break my scarab instance?
+ </b></question>
+ <answer>
+<p>It shouldn't. The way the scarab import works is that it first parses the
+passed xml to import to ensure all dependencies resolve, and that all modules,
+users, attributes and attribute options mentioned in the xml exist. If any
+are missing, then the entire import fails and a report is produced listing the
+problems found ("No such user 'jon'", etc.). If importing via the UI, the
+error report shows in the result screen. If importing via ant, check the
+scarab-xmlimport.log file. If the validation parse runs to the end w/o error,
+then begins the insertion parse.
+</p>
+<p>Note, the scarab validation parse mentioned above is
+distinct from an xml validation parse: The latter checks the validity of the
+xml submitted, the former examines the data contained in the xml making sure
+its coherent with respect to scarab.
+</p>
+ </answer>
+</faq>
+<faq id="23">
+<question><b>
+ What can I do via xml import?
+ </b></question>
+ <answer>
+The import of 'new' issues has been well tested. Updating extant issues
+w/ comments, etc., works at least for the simple cases but is in need of
+testing. The import of dependencies amongst issues works but it too is
+in need of testing, and has some limitations and requirements if included
+as part of an initial issue import.
+ </answer>
+</faq>
+<faq id="24">
+<question><b>
+ Does import support the import of inter-issue dependencies?
+ </b></question>
+ <answer>
+You cannot declare dependencies between separate scarab xml files being
+imported; dependencies can only be reliably established (that is, reconciled)
+within a single xml import file. The way dependencies are done is that on
+import, after the validation parse and insert of issues, a dependency resolving
+step runs: It 'decorates' the just inserted issues w/ the interdependencies
+mentioned in the xml (providing certain information, like activity-set id,
+is correctly set between issues). This step must happen after insert because
+in order to make the interdependencies, the actual scarab issue ids must
+exist. At this time, it does not seem as though you can add dependencies
+via the xml import update mechanism.
+ </answer>
+</faq>
+<faq id="25">
+<question><b>
+ I want to import users and attributes. Can I?
+ </b></question>
+ <answer>
+You cannot currently import nor export modules, users, attributes nor
+attribute options. This facility is to be added soon.
+ </answer>
+</faq>
+<faq id="26">
+<question><b>
+ When would I start a new activity set?
+ </b></question>
+ <answer>
+<p>You'd start a new activity-set when:
+ <ol>
+ <li>Importing an issue and its initial state.</li>
+ <li>Adding physical attachments to an issue.</li>
+ <li>Adding comments to an issue (Scarab treats attachments and comments as
+ roughly equivalent).</li>
+ <li>Adding an <i>activity</i> entry: e.g., one or more state changes such
+ as 'Changed from NEW to STARTED', or issue dependencies.</li>
+ </ol>
+</p>
+ </answer>
+</faq>
+<faq id="27">
+<question><b>
+ How does workflow affect xml import?
+ </b></question>
+ <answer>
+Workflow is disabled in the importing thread so there should be no
+ possibility for conflict.
+ </answer>
+</faq>
+<faq id="28">
+<question><b>
+ Are there sample xml issues that I can study?
+ </b></question>
+ <answer>
+<ul>
+ <li>/src/extensions/update-example.xml is an Example that updates an existing
+ issue adding a comment.</li>
+ <li>/src/extensions/interdependencies.xml is an Example that imports 3 issues
+ preserving the dependency issue 3 has on issue 1.</li>
+</ul>
+ </answer>
+</faq>
+<faq id="29">
+<question><b>
+ Why when I import is issue 'created-by' not respected?
+ </b></question>
+ <answer>
+<p>What may be happening is that the activity-set id in your xml may be that
+of an already existing activity-set; you may be picking up the 'created-by'
+of the activity-set that already exists in scarab. Ensure your activity-set
+id is definetly not that of an already existing activity-set in scarab.
+This section from the scarab.dtd is pertinent:
+<pre>
+ The activity-set id passed is checked against the db to see if
+ this activity-set already exists (The activity-set id
+ == SCARAB_TRANSACTION.TRANSACTION_ID). If the activity-set id
+ does not refer to an already-existing activity-set, a new
+ activity-set id is created by taking the next id off the top of
+ auto-incrementing sequence; the passed activity-set id is
+ discarded. If an activity-set w/ the passed id already exists,
+ then we'll use the already-existing activity-set during import of
+ this activity-set's activites. To avoid picking up an extant
+ activity-set unintentionally on import, i.e. in the case where
+ you are doing an import of all new issues w/ no desire to refer
+ to already existing activity-sets, do not use a purely numerical
+ id for your activity-set id: Give the activity-set an alphabetic
+ prefix. In other words, instead of using numeric ids like
+ 1,2,3,4,5, use ids that run new1, new2, new3, etc. Or simply do not
+ supply the id element at all. The latter is what the jira import xsl
+ does.
+</pre>
+
+</p>
+ </answer>
+</faq>
+<faq id="30">
+<question><b>
+How could I control the encoding of the generated XML?
+</b></question>
+<answer>
+<p>By default, Scarab will set the generated XML to <b>encoding="UTF-8"</b>.
+You can set other target encoding (for example, iso-8859-1) in the scarab.dataexport.encoding
+property.
+<pre> scarab.dataexport.encoding=iso-8859-1
+</pre>
+</p></answer>
+</faq>
+<faq id="31">
+<question><b>How I do an import from Excel or from a simple XML from other systems?</b>
+</question>
+<answer>
+Take a look at the ant script in dir '$SCARAB__ROOT/extensions/excel2scarab'.<br/>
+The instructions are <a href="http://scarab.tigris.org/svn/scarab/trunk/extensions/excel2scarab/README">here</a>.<br/>
+This should make it easy to prepare a valid XML for Scarab from other 'flat' data files.
+If you want you can check it out from Scarab's repository:
+<pre>
+svn co http://scarab.tigris.org/svn/scarab/extensions/excel2scarab
+</pre>
+</answer>
+</faq>
+ </part>
+
+
+<part id="cheapworkflow">
+ <title>Default workflow questions and answers</title>
+ <faq id="31">
+ <question><b>
+ Can I have some values in a dropdown list restricted when editing, but visible when querying?
+ </b></question>
+ <answer>
+ An example of this would be a "Target Milestone" list, where I want to disable the released milestones
+ but still be able to search them. If my milestones are:
+<pre>
+ Release 0.8
+ Release 0.9
+ Release 1.0
+ Release 1.1
+ Release 1.2
+ Release 1.3
+ Deferred to future
+</pre>
+ and I've already released 1.0, I'd define this transitions (Global attribute definition screen) setting the needed role to "Any role"
+ and defining no conditions,
+<pre>
+ Any option -> Release 1.1
+ Any option -> Release 1.2
+ Any option -> Release 1.3
+ Any option -> Deferred to future
+</pre>
+
+ This will disable non mentioned releases when editing issues.
+ </answer>
+ </faq>
+ <faq id="32">
+ <question><b>I've added a blocking dependency to my issue, but I cannot see how this affects to it.</b></question>
+ <answer>
+ Blocking is designed to be configurable, and dependant on the issue type and module of an issue. It's based in a few concepts:<br/>
+ <ul><li>Blocking dependency: A dependency between two issues, with the verb "is blocked by". This is needed for the blocking system
+ to work, but it's not enough for an issue to appear as "Blocked".</li>
+ <li>Blocking issue: An issue in a "Blocking" state (values in attributelists), that will make other issues that are "blocked by" it to be "Blocked".</li>
+ <li>Blocking condition: Defined for a given issue type in a module, is the condition that, if True, will make an issue "Blocking".</li>
+ <li>Blocked issue: An issue with any dependency via an "is blocked by" verb on any issue that is currently a "Blocking issue".</li>
+ </ul>
+ So you should have defined beforehand the blocking condition for your potentially blocking issuetypes. <b>Only when an issue's actual values
+ make that condition true, will the issue block those being "blocked by" it.</b><br/>
+ Whenever an issue is currently blocked or blocking, you will get a notification in the attributes Tab.
+ </answer>
+ </faq>
+ <faq id="33">
+ <question><b>Ok, my issue now appears as "Blocked", but I don't want my users to change the state of a blocked issue!</b></question>
+ <answer>
+ You can restrict the state-transitions that are availaible for a given attribute list. Use the "Disabled if blocked" checkbox in the transition
+ definition subscreen (Global Attributes). This way, you're enforcing the workflow, so the blocking issues will have to be resolved before the
+ blocked one can make the state transition.
+ </answer>
+ </faq>
+ <faq id="34">
+ <question><b>
+I'm looking for a way to let a new issue appear in status "new"
+immediately after sending and without interaction of any person. If I
+use the transition from "empty option" to "new", scarab presents a
+checkbox for the "new" status. I would like to avoid this checkbox.
+ </b></question>
+ <answer>
+Additionally to defining the "empty->new" transition, you should set the field
+as "Required" in this issue-type. Thus, as the only possible value for a new issue will be "new", this value will be "hardcoded" in this moment.
+ </answer>
+ </faq>
+</part>
+</faqs>
Removed: branches/release/0.22/xdocs/faqs.fml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/faqs.fml?view=markup&pathrev=10886
Modified: branches/release/0.22/xdocs/guides.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/guides.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/guides.xml (original)
+++ branches/release/0.22/xdocs/guides.xml 2010-02-03 04:12:05-0800
@@ -19,19 +19,16 @@
<subsection name="Scarab User's Guide">
<ul>
<li>English version <a href="docbook/scarab-user-en.pdf">PDF</a> <a href="docbook/scarab-user-en.html">HTML</a></li>
- <li>French version <a href="docbook/scarab-user-fr.pdf">PDF</a> <a href="docbook/scarab-user-fr.html">HTML</a></li>
</ul>
</subsection>
<subsection name="Scarab Administration Guide">
<ul>
- <li>English version <a href="docbook/scarab-admin.pdf">PDF</a> <a href="docbook/scarab-admin.html">HTML</a></li>
- <li>French version <a href="docbook/scarab-admin-fr.pdf">PDF</a> <a href="docbook/scarab-admin-fr.html">HTML</a></li>
+ <li>English version <a href="docbook/scarab-admin-en.pdf">PDF</a> <a href="docbook/scarab-admin-en.html">HTML</a></li>
</ul>
</subsection>
<subsection name="Scarab Developer's Guide">
<ul>
<li>English version <a href="docbook/scarab-dev-en.pdf">PDF</a> <a href="docbook/scarab-dev-en.html">HTML</a></li>
- <li>French version <a href="docbook/scarab-dev-fr.pdf">PDF</a> <a href="docbook/scarab-dev-fr.html">HTML</a></li>
</ul>
</subsection>
<p>
Modified: branches/release/0.22/xdocs/howto/ant-build-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/ant-build-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/ant-build-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/ant-build-howto.xml 2010-02-03 04:12:05-0800
@@ -73,42 +73,58 @@
other databases see the specific informations [FIXME] Where are these infos?[HD]
</p>
-<p><b>create-custom-property-file</b><br/>
-Regenerates the <i>custom.properties</i> from the <i>build.properties</i>
-You may use this target whenever you have changed properties in your
-<i>build.properties</i> which must propagate to your runtime environment.
-If you don't want to redeploy the whole webapplication, just start
-this target and then restart tomcat. Please note, that in general
-it is NOT sufficient to simply copy your <i>build.properties</i>
-to your <i>custom.properties</i>.
-</p>
-
-<p><b>generate-om</b><br/>
-Generates the java-sources of the Torque Database layer. This target is
-normally used internally from other Ant tasks. But if you want to manually
-recreate the sources files alone, this target is your choice.
-</p>
-
-<p><b>compile</b><br/>
-Generates the class files out of the java sources.
-</p>
-
<p><b>clean</b><br/>
Removes the target files in ../target/scarab. You may want to clean
your installation before rebuilding Scarab in order to ensure your
runtime system is consistent with your source tree.
</p>
-<p><b>clean-all</b><br/>
-Like clean but also removes any logfiles in the tomcat/logs directory
-</p>
-
<p><b>war</b><br/>
Creates a ready to distribute war file.
</p>
+<p><b>create-custom-property-file</b><br/>
+Regenerates the <i>custom.properties</i> and <i>defaultCustom.properties</i> from the <i>build.properties</i>
+You may use this target whenever you have changed properties in your
+<i>build.properties</i> which must propagate to your runtime environment.
+If you don't want to redeploy the whole webapplication, just start
+this target and then restart tomcat.
+</p>
+
+<p><b>compile</b><br/>
+Generates Scarab sources only, e.g. custom property files are missing.
+</p>
</subsection>
</section>
-
+<section name="Properties">
+ <table>
+ <tr>
+ <th>Property name</th>
+ <th>Optional</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>skip.jira.templates.data</td>
+ <td>Yes</td>
+ <td>
+ True = Jira templates for default database should be skipped.
+ </td>
+ </tr>
+ <tr>
+ <td>skip.seed.data</td>
+ <td>Yes</td>
+ <td>
+ True = Users, modules and issues for default database should be skipped.
+ </td>
+ </tr>
+ <tr>
+ <td>skip.default.data</td>
+ <td>Yes</td>
+ <td>
+ True = Default global data (issue types, attributes, ...) for default database should be skipped.
+ </td>
+ </tr>
+ </table>
+ </section>
</body>
</document>
Modified: branches/release/0.22/xdocs/howto/build-docs-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/build-docs-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/build-docs-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/build-docs-howto.xml 2010-02-03 04:12:05-0800
@@ -19,10 +19,12 @@
<subsection name="Generating Maven Managed Docs">
<p>
Documentation should all be written in the xdoc format, and stored under the /xdocs directory. When you
- are ready to generate the documentation, you can run Maven's site generation goal via 'maven site'. If you don't
- want to bother to run the unit tests, then run 'maven site -Dmaven.test.skip=true'. This will generate all
- the site documentation, as well as the FAQ, Javadocs, and various code analysis reports in the directory "/target/docs".
+ are ready to generate the documentation, you can run Maven's site generation goal via: <source>maven site</source>
+ If you don't want to bother to run the unit tests, then run: <source>maven site -Dmaven.test.skip=true</source>
+ This will generate all the site documentation, as well as the FAQ, Javadocs, and various code analysis reports in the directory /target/docs.
</p>
+ </subsection>
+ <subsection name="Used Plugins">
<p>
We use a Tasks plugin from <a href="http://maven-plugins.sourceforge.net/maven-tasks-plugin/">Maven-Plugins</a>
to generate the roadmap document. This plugin should download automatically and install. If not, look at the
Modified: branches/release/0.22/xdocs/howto/build-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/build-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/build-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/build-howto.xml 2010-02-03 04:12:05-0800
@@ -8,28 +8,16 @@
</properties>
<body>
-
-
<section name="The Scarab Build System">
-<subsection name="introduction">
+<subsection name="Introduction">
<p>
The installation and configuration of Scarab is intended to be as simple as
-possible. This document outlines the directory structure of the distribution
-(currently it mirrors the CVS tree), the requirements for running Scarab,
+possible. This document outlines the directory structure of the distribution, the requirements for running Scarab,
the instructions for building and running an installation as well as
requirements for setting up the database.
</p>
<p>
-If you are doing development work with Scarab, please make sure to read
-</p>
-
-<source>
-<a href="http://www.solitone.org/scarab_doc/">http://www.solitone.org/scarab_doc/</a>
-<a href="http://www.solitone.org/scarab_doc/howto/build-howto.html">http://www.solitone.org/scarab_doc/howto/build-howto.html</a>
-</source>
-
-<p>
In this document we use the following logical locations:
<ul>
<li>$SCARAB_ROOT<br/>
@@ -46,12 +34,12 @@
</p>
</subsection>
-<subsection name="requirements">
+<subsection name="Requirements">
<p>
<ul>
-<li>SDK 1.3.1 or higher available from
+<li>SDK 1.4 or higher available from
<p>
<code>
<a href="http://java.sun.com/">http://java.sun.com/</a>
@@ -68,7 +56,7 @@
</p>
</li>
-<li>Maven-1.0 or higher available from
+<li>Maven-1.x available from
<p>
<code>
<a href="http://maven.apache.org/">http://maven.apache.org/</a>
@@ -108,7 +96,7 @@
<li>An RDBMS preferably one out of the list below
<p>
<ul>
- <li>MySQL 3.23.x/4.0.x available from
+ <li>MySQL 3.23.x/4.0.x or higher available from
<p>
<code>
<a href="http://www.mysql.com/">http://www.mysql.com/</a>
@@ -156,10 +144,6 @@
</ul>
</p>
<p>
- NOTE: More detailed instructions for setting up the database on
- different database vendors are available on our website.
- </p>
- <p>
There are also several other databases with partial support:
MS SQL Server, Oracle and DB2. At least oracle and
DB2 have known problems, but we do encourage people to try these
@@ -290,23 +274,27 @@
</p>
<source>
scarab
- +- build <-- Ant scripts for building the sample webapp
- | and creating/loading the sql scripts.
+ +- build <-- Ant scripts for building the sample webapp
+ | and creating/loading the sql scripts.
+- extensions
- | +- usermods <-- place your modifications to the standard
- | | distribution here. These modifications will be
- | | incorporated into the build. This simplifies
- | | the process of replacing *.vm files,
- | | among other things.
- | +- scripts <-- Helper shell scripts
- | +- dtd <-- DTD's for validating XML files
- | +- bugzilla <-- Scripts for converting from Bugzilla to Scarab
+ | +- backup <-- A tool to help backup and restore a Scarab database
+ | +- bugzilla <-- Scripts for converting from Bugzilla to Scarab
+ | +- dtd <-- DTD's for validating XML files
+ | +- excel2scarab <-- Ant build which transforms an XML input file into an XML importable by Scarab.
+ | +- scripts <-- Helper shell scripts
+ | +- usermods <-- place your modifications to the standard
+ | distribution here. These modifications will be
+ | incorporated into the build. This simplifies
+ | the process of replacing *.vm files,
+ | among other things.
+- lib
- +- src <-- The source files.
- +- tomcat <-- Included Tomcat configured ready to run with Scarab.
- +- www <-- Scarab Website
- +- repository <-- The .jar repository for jars used by Scarab.
- +- xdocs <-- xml versions of manuals (guides, howtos etc)
+ +- src <-- The source files.
+ +- tomcat <-- Included Tomcat configured ready to run with Scarab.
+ +- www <-- Scarab Website
+ +- book <-- xml versions of manuals (guides)
+ +- dtd <-- DTD's
+ +- repository <-- The .jar repository for jars used by Scarab.
+ +- xdocs <-- xml files for maven site (misc documentation files, howtos etc)
</source>
<p>
Within the /src directory you find following subdirectories...
@@ -314,20 +302,20 @@
<source>
src
+- conf
- | +- conf <-- Various configuration files for Scarab.
- | | TurbineResources.properties and Scarab.properties
- | | live here. Copied to WEB-INF/conf
- | +- classes <-- Various configuration files copied directly
- | into the classpath.
- +- java <-- The Java source code for Scarab.
- +- migration <-- Java source for migration ant tasks
- +- schema <-- database schema files
- +- sql <-- SQL files for defining the database.
- +- templates <-- ??? [FIXME] what is tis for ???
- +--test <-- Test suite code.
- +--webapp <-- All the web resources required for Scarab like
- | images, css files, javascript files, html files,
- | velocity templates.
+ | +- conf <-- Various configuration files for Scarab.
+ | | TurbineResources.properties and Scarab.properties
+ | | live here. Copied to WEB-INF/conf
+ | +- classes <-- Various configuration files copied directly
+ | into the classpath.
+ +- java <-- The Java source code for Scarab.
+ +- migration <-- Java source for migration ant tasks
+ +- nsis <-- Scripts for nsis (Nullsoft Scriptable Install System)
+ +- schema <-- database schema files
+ +- sql <-- SQL files for defining the database.
+ +- test <-- Test suite code.
+ +- webapp <-- All the web resources required for Scarab like
+ images, css files, javascript files, html files,
+ velocity templates.
</source>
@@ -369,7 +357,7 @@
</p>
<p>
Please note that the properties modified in <code>build.properties</code>
-<b>only</b> affect the build. Changing them and then immediately restarting
+only affect the build. Changing them and then immediately restarting
your appliation server has no effect at all - see the following section
on runtime properties for more information.
</p>
@@ -520,6 +508,9 @@
in <i>custom.properties</i> or by using the JNDI tree as discussed above.
</p>
<p>
+Maybe you have to edit some more properties. For more explanations, you may look into the properties guide.
+</p>
+<p>
You will need to stop and restart Scarab/Tomcat for the changes to take
effect.
</p>
@@ -547,7 +538,7 @@
the webapp directory and is set to <code>WEB-INF/attachments</code>.
You can also define an absolute path such as
</p>
- <code>/bigdisk/scarab/attachments</code>.</li>
+ <code>/bigdisk/scarab/attachments</code></li>
</ol>
<p>
It is recommended to also set the property
@@ -716,26 +707,17 @@
You find more informations about the settings in <code>project.properties</code>
</p>
<p>
-NOTE: PostgreSQL users should follow a different procedure for creating
- the database. See PostgreSQL.txt.
-</p>
-<p>
NOTE: If you would like to only load the required database data and not
the sample/default data, you can do so by passing the property
</p>
- <source>ant create-db -Dskip.seed.data=true</source>
+ <source>ant create-db -Dskip.seed.data=true -Dskip.default.data=true -Dskip.jira.templates.data=true</source>
<p>
to your JVM upon startup of the build processs or by adding the
same property to your <i>build.properties</i>:
</p>
- <code>skip.seed.data=true</code>
-<p>
-NOTE: More detailed instructions for setting up the database on
- different database vendors is available on our website.
-</p>
-<code>
-<a href="http://scarab.tigris.org/project_docs.html">http://scarab.tigris.org/project_docs.html</a>
-</code>
+ <code>skip.seed.data=true
+ ...
+ </code>
<p>
NOTE: The create scripts will attempt to first drop your scarab database
and then recreate it. If you execute "ant create-db", all of your
@@ -752,7 +734,7 @@
</p>
<p>
NOTE: On some operating systems, there seems to be an unexpected
- interation between the JVM, DNS resolution and the MySQL driver
+ interaction between the JVM, DNS resolution and the MySQL driver
where a JDBC url pointing to 'localhost' will resolve as
'localhost.localdomain' and will prevent the connection to MySQL
from authenticating correctly because most people configure MySQL
@@ -772,13 +754,9 @@
<source>
echo "GRANT ALL ON scarab.* to ''@localhost" | mysql mysql
</source>
- Here are a couple of links to also help you solve possible
- permissions problems:
+ See documentationof <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Access_denied">MySQL-manual</a>, too, to solve possible
+ permissions problems.
</p>
-<code>
- <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Access_denied">MySQL-manual</a><br/>
- <a href="http://sourceforge.net/docman/display_doc.php?docid=8968&group_id=15923">docman-display_doc.php</a><br/>
-</code>
</subsection>
@@ -796,7 +774,7 @@
Then, in your web browser, go to:
</p>
<source>
-<http://localhost:8080/scarab>
+http://localhost:8080/scarab
</source>
<p>
NOTE: Make sure that your TOMCAT_HOME is defined correctly. If you are
@@ -816,22 +794,19 @@
<subsection name="Customizing Scarab">
<p>
At times it may be useful to make minor modifications to Scarab without
-applying those changes directly to the Scarab sources (since this
-will cause CVS to report those differences, and even worse, the custom
-modifications might get unintentionally checked into the Scarab CVS
-repository by a Scarab developer).
+applying those changes directly to the Scarab sources.
</p>
<p>
-The extensions/usermod directory structure allows this to be done
+The extensions/usermods directory structure allows this to be done
fairly simply.
</p>
<p>
It contains three directories, lib, conf, and templates. Any files in
the lib directory will be copied into the appropriate target
-directory _after_ any such files in the standard distribution,
-and will replace the standard distribution files. Any files in the
+directory <b>after</b> any such files in the standard distribution,
+and will <b>replace</b> the standard distribution files. Any files in the
template directory will be copied to the target template directory
-_ONLY_IF_ the property "scarab.copy.templates" is set, again after
+only if the property "scarab.copy.templates" is set, again after
the files from the standard distribution.
</p>
<p>
Modified: branches/release/0.22/xdocs/howto/customize-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/customize-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/customize-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/customize-howto.xml 2010-02-03 04:12:05-0800
@@ -59,7 +59,38 @@
</source>
</p>
</subsection>
+<subsection name="Web Context Changes">
+<p>
+Change the tomcat context tag so that reloadable=false. Or, alternatively, change it to true, but
+set the checkInterval to a larger number like 180.
+</p>
+</subsection>
+
+<subsection name="TurbineResources Changes">
+<p>
+You should change the TurbineResources.properties parameters so that velocity templates don't
+auto-reload. Set scarab.template.cache=TRUE to have caching turned on.
+</p>
+</subsection>
+<subsection name="Tuning the cache">
+<p>
+Scarab cache is central in the user experience of performance.
+You might want to take a look at the cache configuration file in:
+<pre>src/conf/classes/cache.ccf</pre>
+
+There you can tweak the number of objects (MaxObjects) of every type that will be kept in memory.
+<ul>
+<li>Module: If your instance is known to be limitated to a given number of modules, this should get a similar
+range.</li>
+<li>ScarabUser: Must be an aproximation to the maximum concurrent number of users.</li>
+<li>Issue: A minimum equivalent to the ScarabUser's would be fine. Maybe something more, to keep a performance margin.</li>
+</ul>
+</p>
+<p>
+<b>Keep in mind: The greatest the size of the cache, the better performance AND the greater memory needs.</b>
+</p>
+</subsection>
</section>
Modified: branches/release/0.22/xdocs/howto/firewall-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/firewall-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/firewall-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/firewall-howto.xml 2010-02-03 04:12:05-0800
@@ -12,103 +12,92 @@
<section name="The problem">
<ul>
-<li>You want to setup Scarab in your company.</li>
-<li>You want Scarab to be accessible from the internet
- throug your company firewall.</li>
-<li>The only open port to the internet is port 80,
- and this port occuppied by your company webserver</li>
+ <li>You want to setup Scarab in your company.</li>
+ <li>You want Scarab to be accessible from the internet
+ throug your company firewall.</li>
+ <li>The only open port to the internet is port 80,
+ and this port occuppied by your company webserver</li>
</ul>
</section>
<section name="The solution (for unix/linux based servers)">
-<p>
-<pre>
-1.) Add a "webspace" to your company webserver.
- for apache the simplest way is as follows:
-
- Add following two lines to your server conf,
- e.g. within your virtual host config:
-
- ProxyPass /scarab http://ScarabHost:8080/scarab
- ProxyPassReverse /scarab http://ScarabHost:8080/scarab
-
- You need to adjust the host:port settings to your environment.
- I also assume, you have mod_proxy added in your apache
- configuration.
- You can attach scarab in multiple ways to your webserver,
- but this is by far the easiest approach...
-
-2.) Setup your "build.properties" for scarab as follows:
-
- The following build properties are essential. You might
- want to change others too. Please follow the instructions
- in the scarab-installation manual and adjust the values below
- according to your environment:
-
- scarab.context=scarab
- scarab.http.domain=www.yourCompany.com
- scarab.http.port=80
- scarab.email.domain=yourCompany.com
- scarab.tomcat.port=8080
- scarab.tomcat.proxy.name="www.yourCompany.com"
- scarab.tomcat.proxy.port="80"
-
- Note: The trick is to set scarab.http.port to 80, NOT to 8080
- The other trick is to surround the proxy settings with double quotes
-
-3.) build scarab as described in thje installation manual
-
-4.) go to target/conf/server.xml
- check that you have the following lines:
- <source>
-<![CDATA[
- <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
- port="9023" minProcessors="5" maxProcessors="75"
- enableLookups="true" redirectPort="8443"
- acceptCount="10" debug="0" connectionTimeout="60000"
- proxyName="www.yourCompany.com"
- proxyPort="80" />
-]]>
- </source>
-
- Sometimes the scarab build drops these (erroneous) lines instead:
- <source>
-<![CDATA[
- <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
- port="9023" minProcessors="5" maxProcessors="75"
- enableLookups="true" redirectPort="8443"
- acceptCount="10" debug="0" connectionTimeout="60000"
- "www.yourCompany.com"
- "80" />
-]]>
- </source>
- Note: proxyPort and proxyName are missing. Correct this manually if
- necessary.
-
-
-5.) build the database as described in the installation manual.
- If you already have a database, skip this point.
-
- cd $root/src/sql
- ./create-db.sh
-
-
-6.) (re-)start scarab
-
- cd target/bin
- ./catalina.sh start
-
-7.) restart your webserver
-
-
-Now you can access your scarab from
-
- http://www.yourCompany.com/scarab/issues
-
-from within your intranet AND from the internet.
-</pre>
-
-</p>
+ <p>
+ Add a "webspace" to your company webserver.
+ for apache the simplest way is as follows:
+
+ Add following two lines to your server conf,
+ e.g. within your virtual host config:
+ <source>
+ ProxyPass /scarab http://ScarabHost:8080/scarab
+ ProxyPassReverse /scarab http://ScarabHost:8080/scarab
+ </source>
+ You need to adjust the host:port settings to your environment.
+ I also assume, you have mod_proxy added in your apache
+ configuration.
+ You can attach Scarab in multiple ways to your webserver,
+ but this is by far the easiest approach...
+ </p>
+ <p>
+ Setup your "build.properties" for Scarab as follows:
+
+ The following build properties are essential. You might
+ want to change others too. Please follow the instructions
+ in the scarab-installation manual and adjust the values below
+ according to your environment:
+ <source>
+ scarab.context=scarab
+ scarab.http.domain=www.yourCompany.com
+ scarab.http.port=80
+ scarab.email.domain=yourCompany.com
+ scarab.tomcat.port=8080
+ scarab.tomcat.proxy.name="www.yourCompany.com"
+ scarab.tomcat.proxy.port="80"
+ </source>
+ Note: The trick is to set scarab.http.port to 80, NOT to 8080
+ The other trick is to surround the proxy settings with double quotes
+ </p>
+ <p>
+ Build Scarab as described in the installation manual.
+ </p>
+ <p>
+ Go to target/conf/server.xml and check that you have the following lines:
+ <source>
+ <![CDATA[
+ <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
+ port="9023" minProcessors="5" maxProcessors="75"
+ enableLookups="true" redirectPort="8443"
+ acceptCount="10" debug="0" connectionTimeout="60000"
+ proxyName="www.yourCompany.com"
+ proxyPort="80" />
+ ]]>
+ </source>
+
+ Sometimes the Scarab build drops these (erroneous) lines instead:
+ <source>
+ <![CDATA[
+ <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
+ port="9023" minProcessors="5" maxProcessors="75"
+ enableLookups="true" redirectPort="8443"
+ acceptCount="10" debug="0" connectionTimeout="60000"
+ "www.yourCompany.com"
+ "80" />
+ ]]>
+ </source>
+ Note: proxyPort and proxyName are missing. Correct this manually if
+ necessary.
+ </p>
+ <p>
+ Build the database as described in the installation manual.
+ If you already have a database, skip this point.
+ </p>
+ <p>
+ (Re-)Start Scarab and your webserver.
+ </p>
+ <p>
+ Now you can access Scarab from
+ <source>http://www.yourCompany.com/scarab/issues</source>
+ from within your intranet AND from the internet.
+ </p>
</section>
</body>
Modified: branches/release/0.22/xdocs/howto/maven-build-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/maven-build-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/maven-build-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/maven-build-howto.xml 2010-02-03 04:12:05-0800
@@ -43,32 +43,18 @@
3:> maven scarab:create-db
</source>
-<ul><li> 1: cd $SCARAB_ROOT<br/>
- go to the root directory of your Scarab source installation.</li>
- <li> 2: maven war:webapp -D maven.test.skip<br/>
- Create the webapp in target/scarab</li>
- <li> 3: maven scarab:create-db<br/>
- Finally create the database. You will be prompted for input.</li>
-</ul>
+This will setup the database and build Scarab's webapp in target/ directory.
-The relevant Maven goals have been summarized and described in the remainder
+Some more relevant Maven goals have been summarized and described in the remainder
of this text.
</p>
</subsection>
-<subsection name="Generating Torque Objects">
+<subsection name="Build sources">
<p>
- Because the the various Torque objects are not checked into CVS,
- but instead are generated based on your settings for the type of
- database, you still need to create the java files.
<source>maven java:compile</source>
- This will create in <code>/src/java</code> the various Torque objects.
-</p>
-<p>
- Only after you have initially generated the Torque objects, you
- can perform all the various functions of Maven that you would
- expect like running unit tests, producing WAR files, etc.
+ This will simply compile Scarab and the various Torque objects.
</p>
</subsection>
@@ -127,40 +113,6 @@
in <code>/target</code> a WAR file that you can then use to deploy
to any Servlet container.
</p>
-<p>
- If you don't already have a configured Tomcat servlet container setup,
- then you can use the embedded Tomcat that comes with Scarab.
- It is in the <code>/tomcat</code> directory.
- To set it up, you just need to put your WAR file in
- <code>/tomcat/webapps/</code>.
- Take the existing
- <code>/tomcat/webapps/scarab.xml</code>
- file and rename it scarab.xml.off, as it is used for inplace development.
-
-</p>
-</subsection>
-</section>
-<section name="In Place Development">
-<subsection name="Intro">
-<p>
- Scarab is setup to do inplace development where the webapp is set
- to be run from the <code>/src/webapp</code> directory.
- This way you can change templates, edit config files and have
- the changes show up immediatly. No need to do a build/deploy/run.
-</p>
-<p>
- Inplace development relies on the embedded Tomcat distribution at /tomcat.
- The maven <code>scarab:inplace</code> goal will automatically setup the
- correct scarab Context file in /tomcat/webapps/:
- <source>maven war:inplace</source>
- This will customize the <code>/tomcat/webapps/scarab.xml</code>
- to point to <code>/src/webapp</code> as
- the root instead of <code>/target/scarab</code>.
-</p>
-<p>
- If you are using an IDE like Eclipse, most changes like editing
- a .java file will automatically restart Turbine for you.
-</p>
</subsection>
<subsection name="Updating the www/repository">
@@ -182,83 +134,43 @@
needed jars to it. Maven gathers the jars from the network if needed.
</p>
</subsection>
-
-<subsection name="Eclipse Setup Directions">
+<subsection name="Clean target">
<p>
- By default, Scarab is setup to use Eclipse as it's IDE.
- To setup Scarab in Eclipse first run the eclipse plugin
- to generate the required files.
- <source>maven eclipse</source>
- In the secnd step you must generate the Torque Objects once, see
- <a href="#Generating_Torque_Objects">"Generating Torque Objects"</a>.
- Finally you can open Eclipse and just import the Scarab directory.
- The .classpath and .project files will be created for you.
-</p>
-<p>
- After you have imported Scarab into eclipse, do a build in Eclipse
- to ensure everything compiles.
-</p>
-<p>
- You will then need to download and install the
- <a href="http://www.eclipsetotale.com/tomcatPlugin.html">Sysdeo Eclipse Tomcat Launcher plugin</a>
- plugin.
-</p>
-<p>
- Restart Eclipse and then go to Window > Preferences and select the Tomcat
- option.
-</p>
-<p>
- First select the Tomcat 4.1.x version of Tomcat, as that is what comes
- with Scarab.
-</p>
-<p>
- Set the tomcat home to:<code>C:\java\scarab\tomcat</code>, then the
- configuration file should be set to:
- <code>C:\java\scarab\tomcat\conf\server.xml</code>.
-</p>
-<p>
- Next you do the Maven part. There is a file called maven.xml that
- contains all the goals needed for setting up inplace development.
- For other IDE's you may need to tweak this.
-</p>
-<p>
- From the root directory run the inplace setup goal.
- <source>maven scarab:inplace</source>
- This copies all the jars, classes, config files needed into your
- <code>/src/webapp/</code> directory, creating
- the <code>/src/webapp/WEB-INF/classes</code> and
- <code>/src/webapp/WEB-INF/conf</code> directories.
- This will also rename your <code>/tomcat/webapps/scarab.xml</code>
- to <code>scarab.regular.xml.off</code>
- and take the special inplace file
- <code>scarab.inplace.xml.off</code> and rename it
- <code>scarab.xml</code>.
-</p>
-<p>
- Now, right click your project in Eclipse and choose properties and
- then Tomcat. Checkbox the "Is Tomcat Project", set the context name
- to <code>scarab</code>, and UNCHECK the update server.xml. Check the
- mark as reloadable and redirect logging to Eclipse options.
- Set the web application root to <code>/src/webapp</code>.
- Save the changes and start up the Tomcat plugin.
- Navigate in your browser to
- <a href="http://localhost:8080/scarab">http://localhost:8080/scarab</a>
- and you should see the login page!
-</p>
-</subsection>
-<subsection name="Eclipse Setup Directions">
-<p>
- Once you are done doing "in place" development, you can just run the goal
- to clean everything back up:
- <source>maven clean</source>
- This will delete everything that was moved around by the inplace setup
- goal, as well as fix up your Scarab context entries as well.
- Now, when you run:
- <source>maven scarab:inplace</source>
- Everything will be put back!
+ Run the following goal to clean everything back up:
+ <source>maven clean</source>
</p>
</subsection>
</section>
-
+<section name="Scarab Maven Properties">
+ <table>
+ <tr>
+ <th>Property name</th>
+ <th>Optional</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>scarab.scarabgen.home=../scarab-gen</td>
+ <td>Yes</td>
+ <td>
+ Location of the scarab-gen project.
+ </td>
+ </tr>
+ <tr>
+ <td>scarab.docs.head=${scarab.scarabgen.home}/www/head</td>
+ <td>Yes</td>
+ <td>
+ Where to store the HEAD version of the documentation.
+ </td>
+ </tr>
+ <tr>
+ <td>scarab.docbook.enable=true</td>
+ <td>Yes</td>
+ <td>
+ Whether to transform docbook documentation. Turn it off if you aren't connected to the
+ internet!
+ </td>
+ </tr>
+ </table>
+ </section>
</body>
</document>
Modified: branches/release/0.22/xdocs/howto/release-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/release-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/release-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/release-howto.xml 2010-02-03 04:12:05-0800
@@ -13,14 +13,7 @@
<section name="Preparations before cutting">
<p>
Basically you need to test and build the distribution, and
- then build and commit the generated documentation. You will need following prerequisites
- to proceed:
- <source>
- maven-1.0.*
- java-1.4 or java-1.5 sdk
- mysql-4.0 or newer
- </source>
-
+ then build and commit the generated documentation.
</p>
<a name="buildtest"/><subsection name="Building a Distribution">
<p>
@@ -33,7 +26,7 @@
<p>
Build and execute tests.
<source>
- maven
+ maven -Dmaven.test.skip=true
maven scarab:create-db
maven test
</source>
@@ -88,7 +81,7 @@
</p>
</subsection>
-<subsection name="Release">
+<subsection name="File Release">
<p>
Build a source release.
@@ -99,14 +92,6 @@
ant package
</source>
</p>
-
- <p>
- Build the All In One Scarab release. This will create a
- Windows executable file that people can run in /target/ directory.
- <source>
- maven scarab:sample
- </source>
- </p>
</subsection>
<subsection name="Restore the 'in development' status for trunk">
<p>
Removed: branches/release/0.22/xdocs/howto/tuning-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/tuning-howto.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/xdocs/howto/windowsdomain-howto.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/howto/windowsdomain-howto.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/howto/windowsdomain-howto.xml (original)
+++ branches/release/0.22/xdocs/howto/windowsdomain-howto.xml 2010-02-03 04:12:05-0800
@@ -46,7 +46,7 @@
<p>
When browsing, Scarab will try to get the credentials and validate them against the NTLM domain.<br/>
If they are valid. it will try logging in the user into Scarab.<br/>
-<strong>For this to succeed, the NTLM usename must match an Scarab username.</strong>
+<strong>For this to succeed, the NTLM username must match an Scarab username.</strong>
</p>
<p>
If the user gets logged in, a message will be displayed, such as <strong>"You've been automatically logged in using your user 'YourUser' from domain 'YourDomain'."</strong>
Modified: branches/release/0.22/xdocs/index.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/index.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/index.xml (original)
+++ branches/release/0.22/xdocs/index.xml 2010-02-03 04:12:05-0800
@@ -126,7 +126,7 @@
already. Build a "target" sandbox, startup Tomcat and explore the
templates that are already there. Analyze the database design and look
at the files in the src/sql directory (the default-data and sample-data)
-files are very helpful. The README.txt file documents everything
+files are very helpful. Scarab's Guides from documentation site contain everything
necessary to get a Scarab installation up and running. It's easy.
</p>
</subsection>
Removed: branches/release/0.22/xdocs/maven_goals.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/maven_goals.xml?view=markup&pathrev=10886
Removed: branches/release/0.22/xdocs/maven_properties.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/maven_properties.xml?view=markup&pathrev=10886
Modified: branches/release/0.22/xdocs/navigation.xml
Url: http://scarab.tigris.org/source/browse/scarab/branches/release/0.22/xdocs/navigation.xml?view=diff&pathrev=10887&r1=10886&r2=10887
==============================================================================
--- branches/release/0.22/xdocs/navigation.xml (original)
+++ branches/release/0.22/xdocs/navigation.xml 2010-02-03 04:12:05-0800
@@ -13,7 +13,6 @@
<menu name="General Information">
<item name="Overview" href="/index.html"/>
<item name="Installation" href="/howto/build-howto.html"/>
- <item name="1.0 Roadmap" href="/tasks-report.html"/>
</menu>
<menu name="Documentation">
@@ -22,7 +21,6 @@
<!-- Note, name of properties is scarab_properties_final.html due to encoding issues forcing
some name changes -->
<item name="Properties Guide" href="/scarab_properties_final.html"/>
- <item name="FAQ" href="/faqs.html"/>
<item name="How-To's" href="/howto/index.html" collapse="true">
<item name="Maven Build" href="/howto/maven-build-howto.html"/>
<item name="Ant Build" href="/howto/ant-build-howto.html"/>
@@ -30,7 +28,6 @@
<item name="Releasing Scarab" href="/howto/release-howto.html"/>
<item name="Scarab and Firewalls" href="/howto/firewall-howto.html"/>
<item name="Windows domain auth" href="/howto/windowsdomain-howto.html"/>
- <item name="Tuning Howto" href="/howto/tuning-howto.html"/>
<item name="Customizing Scarab" href="/howto/customize-howto.html"/>
</item>
<item name="Databases" href="/databases/index.html" collapse="true">
@@ -51,16 +48,11 @@
<item name="XML Import" href="/xmlimport/index.html" collapse="true">
<item name="Import Issues" href="/xmlimport/import-issues.html"/>
<item name="XML Format" href="/xmlimport/xml-format.html"/>
- <item name="XML FAQ" href="/faqs.html#22"/>
+ <item name="XML FAQ" href="/faq.html#22"/>
</item>
- <item name="Changes" href="/changes-report.html"/>
<item name="JavaDocs" href="/apidocs/index.html"/>
<item name="L10N Status Report" href="/l10nstatus.html"/>
</menu>
- <menu name="Maven Goals">
- <item name="Goals" href="/maven_goals.html" />
- <item name="Properties" href="/maven_properties.html" />
- </menu>
<menu name="Project Tools" collapse="true">
<item name="Membership" href="http://scarab.tigris.org/servlets/ProjectMemberList" />
------------------------------------------------------
http://scarab.tigris.org/ds/viewMessage.do?dsForumId=3577&dsMessageId=2444432