[Agila Wiki] Update of "AgilaBpelInstallationGuide" by MatthieuRiou

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Agila Wiki" for change notification.

The following page has been changed by MatthieuRiou:
http://wiki.apache.org/agila/AgilaBpelInstallationGuide

New page:
= Agila BPEL Installation Guide =

== Prerequisites ==

To run properly Agila BPEL needs to run inside a servlet container and connect to two types of databases : a relational database and an XML database. You will also need [http://ant.apache.org Apache Ant] to use our scripts.

You just need to have an installed version of Tomcat on your computer to install Agila BPEL. Installing Tomcat is simple (as simple as download and unzip) so that shouldn't be a big problem. Agila BPEL is working with the latest versions of Tomcat 4.1 but we recommend using Tomcat 5 (some weird exceptions are logged with Tomcat 4 even when it's working alright). Installing Agila BPEL in another web container shouldn't be a problem either.

The other thing you will need is a relational database installation. For testing and playing around, Agila BPEL is shipped with HSQL-DB , an open source relational database written in Java but even if HSQL is a pretty fast database it doesn't scale very well so we wouldn't recommend using it in production. Agila BPEL can be integrated with a large variety of databases like MySQL, Oracle, DB2, Sybase…  We will explain later how to setup Agila BPEL to use HSQL first and then your own database server.

You shouldn't worry about the XML database as Agila BPEL is also shipped with a XML database : Apache Xindice. We will explain how to install it later (it's also rather easy) in this document.

Right now Agila BPEL hasn't been released yet, so the only way to obtain a distribution is to build it yourself. But don't worry, building Agila BPEL isn't hard if you have to right tools.

== Obtaining Agila BPEL ==

To obtain Agila BPEL, you have to checkout the sources from our Subversion repository. Install a [http://subversion.tigris.org/project_packages.html Subversion client] and run:

{{{ 
svn http://svn.apache.org/repos/asf/incubator/agila 
}}}

You are now a happy owner of Agila :)

== Building Agila BPEL ==

Before building Agila BPEL, you will need to download the following softwares:
 * [http://maven.apache.org Apache Maven]
 * [http://xdoclet.sf.net XDoclet 1.2.x]

To install Maven, follow the [http://maven.apache.org/start/install.html Installing Maven] guide. XDoclet is only necessary to get XDoclet's Maven plug-in. Extract XDoclet's distribution and copy maven-xdoclet-plugin-1.2.1.jar located in the lib directory in Maven's plugins directory.

Create a file named build.properties in your user's home directory (like /home/username or C:\Documents and Settings\username). Copy and paste the following line into this file:

{{{ 
maven.repo.remote=http://www.ibiblio.org/maven,http://www.smartcomps.org/twister/maven-repo 
}}}

Using a console go to Agila BPEL source distribution root (should be something like agila/trunk/modules/bpel) and type:

{{{ 
maven buildall 
}}}

This will build all Agila BPEL modules. The results of the build are placed in the target directory of each module (usually a jar or a war). The two necessary Agila BPEL web applications that you deploy in Tomcat are in client/web/target and engine/wsa/target.

If you like to do some tweaking or development of Agila BPEL, to build a specific module, use

{{{ 
maven jar:install 
}}}

for a library module and

{{{ 
maven war 
}}}

for a web application module.

But if you just want to use Agila BPEL the two WAR files described above will suffice.

== Deploying in Tomcat ==

In short:

 1. Copy the two war files obtained after compliation to tomcat/webapps.
 2. Copy hsqldb-x.x.jar (or your database's JDBC driver) to tomcat/common/lib.
 3. Copy engine/wsa/src/test/resources/conf/hibernate.cfg.xml and agila-configuration.xml to Tomcat/common/classes.

A default Agila BPEL installation will look for its services on localhost port 8080. To change these settings you will have to update a configuration file named client.properties bundled in agila-client-x.x.jar packaged inside agila-web.war. If you have to update this setting, the best alternative is to remove it from the jar file and then place it anywhere you like in Agila BPEL web application classpath (either in tomcat/common/classes or in tomcat/webapps/agila-web/WEB-INF/classes).

==  Setting the database ==

=== Using HSQL ===

Agila BPEL configuration is using HSQL by default so there is nothing special to setup. The only thing you need to do is starting HSQL and initialize the database. Two Maven goals have been defined in the dist submodule. The first one starts an HSQL instance and the second initializes the database with the right schema. To use these two goals just go to the dist directory and run:

{{{ 
maven hsql:start
maven db:create
}}}

=== Using your own Database ===

Coming soon...

== Testing your installation ==

Run Tomcat and go to http://localhost:8080/agila-web . You should be able to login with admin/admin.