<?xml version="1.0"?>

<document>

  <properties>
    <title>Melati - Java SQL Website Development Engine</title>
    <author email="timp At paneris.org">Tim Pizey</author>
    <keywords>
      Persistence, Java, SQL, Database, Templates, Object Relational Mapping,
      Objects, Object Oriented, J2EE replacement
    </keywords>
  </properties>

  <body>


<!--
  <p align="center">
   <font size="-1"><i>
This page last updated: $Date: 2008/02/22 13:16:34 $ $Author: timp $
   </i></font>
  </p>
-->
  
<!-- menu -->

<section name=" Installation ">
<p>
  The Melati distribution includes a webserver (<a
  href="http://jetty.mortbay.org/" target="jetty">Jetty</a>), a database (<a
  href="http://www.hsqldb.org/" target="hsqldb">HSQLDB</a>) and two 
  templating engines (<a
  href="http://jakarta.apache.org/velocity/">Velocity</a> and 
  <a href="http://www.webmacro.org/">WebMacro</a>) so that it works 
  straight out of the distribution with no configuration.
</p>
<p>
  A completely empty database, which instantiates <a
  href="/melati/xref/org/melati/poem/PoemDatabase.html">org.melati.poem.PoemDatabase</a>
  is configured in the distribution.<br />
  This can be used as your local <a href="/melati-webapp/org.melati.admin.Admin/melatitest/Main">desktop database</a>.
</p>
<subsection name="Maven quick start">
<p>
Install Maven from <a href="http://maven.apache.org/">maven.apache.org</a>.
</p>
<p>
Change directory to a suitable directory (/dist or C:) and download using maven:
<pre>
mvn -DconnectionUrl=scm:cvs:pserver:anonymous@melati.org:/usr/cvsroot:melati -Dpassword=anon -DcheckoutDirectory=melati scm:checkout
</pre>
This will create a directory called melati containing the whole project.
To install and generate the site documentation:
<pre>
cd melati
mvn install site
</pre>
That's it!
</p>
</subsection>
<subsection name="Testing">
<p>
To test your installation and illustrate a few capabilities 
run through the <a href="Testing.html">interactive tests</a> and run the unit tests 
using the following command:
<pre>
mvn test
</pre>
Though the tests are automatically run during the install.
</p>
</subsection>
<subsection name="Extending the contacts example">
<p>
  If you want to use Melati to build a website you might start by 
  downloading and tinkering with the <a
  href="melati-example-contacts/">Contacts example</a> 
  locally, you can, of course change the target database and default
  templating engine.
</p>
</subsection>
<subsection name="Maven archetype">
<p>
  To create a new Melati based project use the <a href="melati-archetype/">archetype</a>.
</p>
</subsection>
<subsection name="Using ant still?">
<p>
Ant is a language, Maven is a build system : stop using Ant, we have.
</p>
<p>
  Further installation instructions are in the <a
  href="/README.html">README</a> file.
</p>
</subsection>
</section>
<section name="Database Setup"> 
<subsection name="HSQLDB">
<p>
Melati works well with HSQLDB, this is set by default to save the database as an SQL script 
upon either servlet container restart or jvm exit, enabling all state to be 
maintained and editted by hand if neccessary. HSQLDB file or memory urls are supported, 
so the data can be persisted or not  as required.
</p>
<p>
There is no setup required for HSQLDB, other than specifying the database url.
</p>
</subsection>
<subsection name="Postgresql">
<p>
Install Postgresql, enable tcp access by adding <tt>-i</tt> to the postmaster options.
</p>
<p>
As the postgres user create your databases:
<pre>
createdb everything
createdb melatijunit
</pre>
</p>
</subsection>
<subsection name="MySQL">
<p>
Install MySQL with support for transactions, to use InnoDb this involves 
uncomenting the innodb section of my.cnf.
</p>
<p>
In Mysql create your databases:
<pre>
CREATE DATABASE everything;
CREATE DATABASE melatijunit;
</pre>
</p>
<p>
Authorise the user that Poem will connect as:
<pre>
USE everything;
GRANT ALL ON *.* to melati@localhost identified by 'melati';
USE melatijunit;
GRANT ALL ON *.* to melati@localhost identified by 'melati';
</pre>
</p>
</subsection>
<subsection name="SQLServer">
<p>
Install SQLServer, enable login access rather than Windows authentication.
Set a user and password
</p>
<p>
In SQLServer Administrator create your databases:
<pre>
everything
melatijunit
</pre>
</p>
</subsection>
<subsection name="MSAccess">
<p>
Create two empty databases called <tt>everything</tt> and <tt>melatijunit</tt>.
</p>
<p>
In ODBC set them as ODBC system DSN datasources, called <tt>everything</tt> and <tt>melatijunit</tt>.
</p>
<p>
There is currently a problem such that you have to rerun the tests a couple of times to get the tables to be recognised, 
the test <tt>DynamicTableTest</tt> needs to be disabled.
</p>
</subsection>
</section>
</body>
</document>






