======== GETTING STARTED =========

These instructions are intended for developers wanting to work on the
source of daisy, and thus explains how to get things running in a development
environment. All other users should use the daisy distro, and follow
the instructions provided with therein.

Creating the MySQL database
---------------------------

Required MySQL version: 4.0.20

Assign access rights: login as root user to mysql:

mysql -uroot -pYourSecretPassword

On some MySQL installations, the root user has no password, in that case drop
the -p parameter.

Then grant the necessary access rights using the following commands: (this will
automatically create the users)

GRANT ALL ON daisyrepository.* TO daisy@"%" IDENTIFIED BY "daisy";
GRANT ALL ON daisyrepository.* TO daisy@localhost IDENTIFIED BY "daisy";

The localhost entries are necessary because otherwise the default access rights
for anonymous users @localhost will take precedence.


Maven installation
------------------

Maven is the tool used to build Daisy.

Download version 1.0 from http://maven.apache.org

Copy a xalan jar file to MAVEN_HOME/lib/endorsed. 
Xalan can be downloaded from http://xml.apache.org/xalan-j/downloads.html

Apparently there is a problem somewhere if the local maven repository is located
in a directory with spaces in the name (default location is ~/.maven). Since this
is by default the case on Windows, users of that OS should work around this by creating
a build.properties file in their home directory (usually c:\document and settings\USERNAME\)
with the following property in it: maven.home.local=d:\\some_directory


Merlin installation
-------------------

Download Merlin 3.3.0 from:

http://www.apache.org/dist/avalon/merlin/binaries/

Installation of merlin simply consists of extracting the archive somewhere,
and letting the environment variable MERLIN_HOME point to the created directory.
Then add MERLIN_HOME/bin to your PATH.

Locate the 3 jar files which you can find in the plugins directory in MERLIN_HOME. 
This directory contains three subdirectories which each contain a /plugin 
directory. The jar file can be found there.

Copy these 3 jars to the MAVEN_HOME/plugins directory.

Torque Maven plugin installation
--------------------------------
We use the Apache Torque generator to generate database-specific database creation
SQL scripts from and XML definition.

The torque Maven plugin can be easily installed like this:

maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.1.1

OpenJMS installation
--------------------

* download OpenJMS version 0.7.6.1 from http://openjms.sourceforge.net/

* unzip, and set OPENJMS_HOME environment variable

* make a database and corresponding users on MySQL:

CREATE DATABASE openjms;
GRANT ALL ON openjms.* TO openjms@"%" IDENTIFIED BY "openjms";
GRANT ALL ON openjms.* TO openjms@localhost IDENTIFIED BY "openjms";

* Put mysql database driver somewhere (e.g. in OPENJMS_HOME/lib),
  and reference it in the CLASSPATH by editing
  OPENJMS_HOME/bin/setenv.sh (or .bat for Windows)

* edit OPENJMS_HOME/config/openjms.xml

Replace the DatabaseConfiguration element with:

  <DatabaseConfiguration>
    <RdbmsDatabaseConfiguration
      driver="com.mysql.jdbc.Driver"
      url="jdbc:mysql://localhost/openjms" 
      user="openjms" 
      password="openjms"
      maxActive="10"
      maxIdle="5"
      evictionInterval="3600"
      testQuery="select current_date" />
  </DatabaseConfiguration>

Replace the AdministeredDestinations element with:

  <AdministeredDestinations>
    <AdministeredTopic name="daisy">
      <Subscriber name="fullTextIndexer"/>
      <Subscriber name="emailNotifier"/>
    </AdministeredTopic>
    <AdministeredQueue name="fullTextIndexerJobs"/>
  </AdministeredDestinations>

Add the following element:

  <SecurityConfiguration securityEnabled="true"/>

By default, a user "admin/openjms" is configured, which is also used
by the default daisy configuration (which is ok in a development
environment, see the daisy distro instructions on how/where to change this
if needed).

* Create the database tables:

dbtool.sh -create -config $OPENJMS_HOME/config/openjms.xml
or
dbtool.bat -create -config %OPENJMS_HOME%\config\openjms.xml

* Start OpenJMS using OPENJMS_HOME/bin/startup.sh

Installing jars in local Maven repository
-----------------------------------------
Daisy requires a number of jars not available in the ibiblio repository.
You can install them directly into your local repository by going to your
Daisy root directory, navigating to the lib directory and executing maven:

cd lib
maven

(Note that we found this to be easier than to work with jar overrides
in Maven and library paths in Merlin block descriptors)

Compiling
---------

Daisy consists of a number of separate projects. The projects can all
be built in one go simply by executing maven in the base daisy directory:

maven

This will build the different artifacts in the correct order and install
them in your local maven repository.

Configuring
-----------

Go to the directory daisy/repository/server

Copy the file myconfig.xml.template to myconfig.xml

Edit the myconfig.xml file and adjust 

1/ the value in the <directory> tags to point to the directories where 
the blobs resp. the index files may be stored. (the directories must exist).
(NOTE: On windows you can use forward slashes in the pathname here.)

2/ the values for the emailer-configuration (fromAddress and smtpHost)

3/ the <driverClasspath> tag should contain the path to the JDBC driver jar.
Usually this is:
/your-home-dir/.maven/repository/mysql/jars/mysql-connector-java-3.0.15-ga-bin.jar

(note: other configuration present in the file
repository-server/src/conf/block.xml can be overridden in
a similar way, such as the database access parameters)

Creating the Repository
-----------------------

1) Go to the daisy root directory.

2) Go to install/target.

3) Execute:   daisy-repository-init-dev
              (linux: sh daisy-repository-init-dev if not executable)

4) This program will ask a number of parameters, which for a development
   environment you can best leave to their defaults, thus simply press
   enter, except:
    * when asked for the password for the user 'internal', enter 'defaultpwd'
    * when you reach the "drop database" question, answer yes.
    * when asked to create a daisy data directory, answer no.

Running the Repository server
-----------------------------

Set the MERLIN_HOME environment variable and point it to your merlin installation. 
Put MERLIN_HOME/bin in your PATH

Execute (from daisy/repository/server):
merlin -repository ~/.maven/repository/ -config myconfig.xml src/conf/block.xml

The -repository argument ensures that merlin uses the same runtime repository as
Maven. This is required because all the daisy jars build during the compiling
step reside there. On Windows you should put an explicit path to your
maven repository after the -repository argument.
E.g. merlin -repository c:\maven_base\repository -config myconfig.xml src/conf/block.xml


Executing testcases
-------------------

There is a set of automated testcasing verifying various parts of the repository
functionality. For information on running these, see the file
repository/test/README.txt

Repository API documentation
----------------------------
To view the repository API documentation, go to the directory
daisy/repository/api and execute:

maven javadoc

Then you can view the javadoc by opening

target/docs/apidocs/index.html

in your browser.

Building and running the Cocoon-based DaisyWiki Application
-----------------------------------------------------------

See applications/daisywiki/README.txt