,-----------------------------------------------------------------------.
| Scarab Quick Start Guide                                              |
'-----------------------------------------------------------------------'

Welcome to Scarab! This document will help you get Scarab up and running
as quickly as possible, with the minimum of fuss.

Before we get started, please ensure that you either have installed

    Maven-1.0 or newer

or if you prefer ant, ensure, that you have installed

    Ant 1.5.x or newer
    
on your system.

We assume that you have a database server up and running, which
is currently supported by Scarab. Currently we support following
databases:

  +----------------+--------------------------------------------------
  | MySQL          | Full support for 4.0 and 4.1
  | PostgreSQL     | Full support (*)
  | MS SQL Server  | partial support [FIXME] what is partial support ?
  | Oracle         | broken
  | Hypersonic     | partial support [FIXME] what is partial support ?
  +----------------+--------------------------------------------------

Please check your security setting. you get some hint from the properties files
project.properties, search the section "SETUP WIZARD" on that file!
e.g. for MySQL the default settings assume database user root has no password
set (which is highly insecure, but convenient for quick installation)

(*) See step 5a for more details.

,-----------------------------------------------------------------------.
| Step 1: Unpack the Scarab distribution
'-----------------------------------------------------------------------'

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. If you are reading this document, you have probably already
completed this step.

,-----------------------------------------------------------------------.
| Step 2: Migrating an old (pre b19) version of Scarab
'-----------------------------------------------------------------------'

Please, read the 2.1 section of the MIGRATION file for instructions on the
migration of your current settings.

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.

,-----------------------------------------------------------------------.
| Step 3: Configure Scarab
'-----------------------------------------------------------------------'

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.

If you don't already have an old build.properties file, create one as
follows:

1.) Go to your $SCARAB_HOME directory

2.) copy (not rename!) one of the following two files to build.properties:

    2a) minimal.properties   (minimal customization property set)

        minimal.properties is your best choice (believe us!). You will
        be doing this in your command line shell (or dos-box):

        cd $SCARAB_HOME
        cp minimal.properties build.properties

    2b) project.properties   (full customization property set)

        You will choose project.properties as your starting point, if you
        are a developer who is deeply involved into the Scarab development.

3.) 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!

,-----------------------------------------------------------------------.
| Step 4: Build Scarab
'-----------------------------------------------------------------------'

You have two choices to build Scarab:

4.1 Maven build:

    1.) Enter the $SCARAB_ROOT directory
    2.) call maven as follows:
    
        maven war -Dmaven.test.skip
        
        NOTE: -Dmaven.test.skip avoids running the junit tests.
              If you want to run also the tests, simply enter
              "maven war" and the tests will be performed. Prepare
              for a significant amount of additional processing time!
              Given the tests are intended to work against a database,
              it's possible that you see them fail in this step if your
              database is not already configured. Look at the

4.2 Ant build:

    1.) Enter the $SCARAB_ROOT/build directory
    2.) call ant as follows:
    
        ant
 
 
,-----------------------------------------------------------------------.
| Step 5a: Create the database                                          |
'-----------------------------------------------------------------------'

*** ONLY IF YOU'RE NOT MIGRATING AN EXISTING INSTANCE OF SCARAB !! ***
*** Read the 'MIGRATION' file if you need to preserve your data !! ***

Now you can create and populate the Scarab database. 
Just run one of the commands bellow:

If you are using ant:

        ant create-db
	
	or
	
        ant -Dskip.seed.data=true create-db

    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.

If you are using maven, similar commands exist:
    
        maven scarab:create-db
        maven -Dskip.seed.data=true scarab:create-db


*** IMPORTANT information for PostgreSQL users ***

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.

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'.

The script can be found at src/sql/postgresql/hack-db.sql in the
distribution, and it can be executed in different ways, for example
from the command line:

postgres> psql scarab < hack-db.sql

where 'scarab' is the name of the Scarab database, and 'postgres' is
the "system" postgreSQL user. Alternatively, from the psql interactive
console:

scarab=> \i hack-db.sql

*** End ***

,-----------------------------------------------------------------------.
| Step 5.b [OPTIONAL] JIRA templates                                    |
'-----------------------------------------------------------------------'

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.

        ant -Dskip.jira.templates.data=true create-db

or

        maven -Dskip.jira.templates.data=true scarab:create-db

This option is independent of 'skip.seed.data', so either or both may
be specified.
       
,-----------------------------------------------------------------------.
| Step 5c: Migrate your current data                                    |
'-----------------------------------------------------------------------'

*** ONLY IF YOU ARE MIGRATING AN EXISTING INSTANCE OF SCARAB !! ***

Go to MIGRATION file for instructions on migrating your existing data.


,-----------------------------------------------------------------------.
| Step 6: [OPTIONAL] Run the tests                                     |
'-----------------------------------------------------------------------'

If you launch the tests now they will run on your recently configured
database. Just do:

       maven test

The results of the tests will be in:

    $(SCARAB_HOME)/target/test-results/

If you'd like to make your tests with other db environment, follow these
steps:

  1. maven clean (you better start from scratch if you gonna test)
  2. Configure your build.properties to contain at least the correct
     scarab.database.type value.
  3. maven war
  4. maven scarab:create-db 
     Be sure, you do not unintentionally overwrite any production data
     by double checking yur build.properties. Per default the database "scarab"
     will be generated and a previous version of the datbase will be scratched!
  5. maven test

,-----------------------------------------------------------------------.
| Step 7: Start Tomcat
'-----------------------------------------------------------------------'

On Windows, double-click on the file

    $SCARAB_HOME/tomcat/bin/startup.bat
    
On Unix/Linux, run the following shell script:

    $SCARAB_HOME/tomcat/bin/startup.sh


The webapplication will be available as reflected by the settings of the
following properties (see step 3):

    scarab.http.scheme
    scarab.http.domain
    scarab.http.port
    scarab.context

In general your Scarab will be available from a browser on the URL:

    ${scarab.http.scheme}://${scarab.http.domain}:${scarab.htp.port}/${scarab.context}

Consequently in case you did NOT change the default properties, you now 
will find Scarab by pointing your Browser to:
 
    http://localhost:8080/scarab
    
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.

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:

    users-subscribe@scarab.tigris.org
   
Once you are subscribed, send a message to users@scarab.tigris.org
detailing your problem.
