Agila BPEL Installation Guide
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 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 won't need to worry much about the XML database as Agila BPEL is well integrated with 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 Subversion client and run:
svn checkout -r [version_number] http://svn.apache.org/repos/asf/incubator/agila
Note: The "version_number" in the above command specifies the version of agila for checkout. a list of current versions can be found by visiting http://svn.apache.org/repos/asf/incubator/agila.
You are now a happy owner of Agila The revision provided is the latest stable version.
Building Agila BPEL
Before building Agila BPEL, you will need to download the following softwares:
To install Maven, follow the Installing Maven 1.X 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. Another solution is adding http://xdoclet.sourceforge.net/repository to the build.properties file.
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:
Using a console go to Agila BPEL source distribution root (should be something like agila/trunk/modules/bpel) and type:
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
for a library module and
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
Before deploying you'll have to download Xindice 1.1b4 to deploy it in Tomcat as well. Just pick the webapp version (http://xml.apache.org/xindice/download.cgi).
- Copy the two war files obtained after compliation to tomcat/webapps.
Copy hsqldb-x.x.jar (or your database's JDBC driver) to tomcat/common/lib. Note: Use the hsqldb-126.96.36.199.jar
- Copy engine/wsa/src/test/resources/conf/hibernate.cfg.xml and agila-configuration.xml to Tomcat/common/classes.
- Copy Xindice war file included in Xindice's distribution in tomcat/webapps (make sure the file name is 'xindice.war').
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
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 modules/bpel/dist directory and run:
maven hsql:start maven db:create
Using your own Database
Agila BPEL is using Hibernate as its persistence layer. Thanks to Hibernate, Twister can support several databases (like MySQL, HSQL, Oracle, DB2, Sybase, MS SQL Server, ...) simply by changing a configuration file. For a full list of supported database servers, please refer to the hibernate web site.
To configure your database server, edit the file hibernate.cfg.xml located in the engine/wsa/src/test/resources directory of your Agila BPEL's sources. Five properties must be changed :
- connection.driver_class : the fully qualified name of the JDBC driver class of your database server.
- connection.url : the JDBC connection URL used to connect to your database.
- connection.username : the user name to login to your database.
- connection.password : the password associated to the login.
- dialect : the hibernate dialect to use.
Hibernate uses different "dialects" depending on the database it has to use. The dialect parameter is therefore specific to each database. Here is a table that lists dialects for most currently used databases:
Microsoft SQL Server
You'll also need to add your JDBC driver as a Maven dependency in the dist module. Edit project.xml in the dist module and add something like this (adapt with your driver name and version) before the dependencies closing tag:
<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>3.0.10</version> </dependency>
Make sure that your database is running and that a database has been created for Agila BPEL (according to the connection URL) and run (still in the dist module):
This should initialize all tables properly. Before restarting Tomcat don't forget to copy your database JDBC driver in tomcat/common/lib and to rebuild the two WAR files (they will be updated with your new Hibernate configuration).
Testing your installation
Run Tomcat and go to http://localhost:8080/agila-web . You should be able to login with admin/admin.