dimanche 13 juin 2010

How to install Bonita on a Glassfish server with an Oracle database

This article is the english translation of Installer Bonita sur un serveur Glassfish avec une BDD Oracle


According to the official documentation, Bonita runtime and user experience can only be installed on JBoss or Tomcat servers. With little patience, those components can be deployed on Glassfish servers.


Introduction to Bonita

Bonita is an open-source workflow solution supported by the BPM company BonitaSoft.

The Bonita solution combines :

  • A standalone process design studio (the Bonita Studio)
  • A BPM engine (the Runtime)
  • A graphical user interface (the Bonita User Experience - BUE)

Goal

The goal of this tutorial is to install the runtime and the BUE on a Glassfish v2.1.1 server. The runtime will use a remote Oracle 10g database (XE). The Bonita Studio will be installed on the administrator's computer.

Process users will connect to the User Experience from a remote computer (WinXP / Firefox). So will the administrator.
The operating system installed on the application and database servers is CentOS 5.5.

In this tutorial, the application server's hostname is bonita.localdomain. The database server's hostname is database.localdomain


Note: this guide only contains information related to the appplication server's configuration. For instance, DBMS installation won't be covered in this article.


Requirements

  • Bonita Studio has already been installed on the administrator's computer
  • Oracle DBMS has already been installed on the database server
  • Glassfish is installed on the application server
  • Ant is installed on the application server

Step 1 - Export the engine

Start Bonita Studio, then click on "Process > Export application".

Check the "Export UserXP" and "All UserXP" checkbox
Check the "Export runtime" checkbox
Check the "Extract selected war libraries {...] in a common folder [...]"
Don't select any process in the process list
Select a location (for instance: /home/pingtimeout/bonita_application.zip)

A file named bonita_application.zip is created in the specified folder.

Unzip this file (e.g. in /home/pingtimeout/bonita_application/). The newly created folder now contains these elements:

  • common-war-lib
  • conf
  • runtime
  • wars
  • INSTALL.txt

Bonita UserXP and Runtime are now ready to be installed.


Step 2 - Create and initialize the databases

Note : in this tutorial, the databases "core" and "history" are stored on the same Oracle instance. However, they could be separated on two different instances.


Create two db users named CORE and HISTORY.

In the bonita_application folder, edit the file runtime/conf/hibernate-core.properties. Change the following parameters:

hibernate.dialect                 org.hibernate.dialect.Oracle10gDialect
hibernate.connection.driver_class oracle.jdbc.OracleDriver
hibernate.connection.url          jdbc:oracle:thin:@database.localdomain:1521:XE
hibernate.connection.username     CORE
hibernate.connection.password     CORE


Edit the file runtime/conf/hibernate-history.properties. Change the following parameters:

hibernate.dialect                 org.hibernate.dialect.Oracle10gDialect
hibernate.connection.driver_class oracle.jdbc.OracleDriver
hibernate.connection.url          jdbc:oracle:thin:@database.localdomain:1521:XE
hibernate.connection.username     HISTORY
hibernate.connection.password     HISTORY


Add the Oracle JDBC driver in runtime/lib/server/


Use ant to create and initialize the core db.
$ ant init-db
Choose the following configuration: hibernate-configuration:core


Use ant to create and initialize the history db.
$ ant init-db
Choose the following configuration: hibernate-configuration:history


The databases are now created and initialized.


Step 3 - Prepare a Glassfish domain

Note : $GLASSFISH_HOME is an environment variable that contains the absolute path to the bonita home directory (on my server : /opt/glassfish/)


Create a glassfish domain named "bonita"
$ asadmin create-domain --adminuser admin --portbase 24000 bonita

Enter the admin password and the master password for this domain to be created.


Copy all files from bonita_application/common-war-lib/ in $GLASSFISH_HOME/domains/bonita/lib/
$ cp bonita_application/common-war-lib/* $GLASSFISH_HOME/domains/bonita/lib/


Copy all files from bonita_application/runtime/lib/server/ in $GLASSFISH_HOME/domains/bonita/lib/
$ cp bonita_application/runtime/lib/server/* $GLASSFISH_HOME/domains/bonita/lib/


Copy all files from bonita_application/runtime/conf/ in $GLASSFISH_HOME/domains/bonita/config/
$ cp bonita_application/runtime/conf/* $GLASSFISH_HOME/domains/bonita/config/


Start the domain
$ asadmin start-domain bonita


The "bonita" glassfish domain is now started.


Step 4 - Install Bonita on Glassfish

Finally, bonita.war may now be uploaded on the application server.


On your domain's administration console (e.g. http://bonita.localdomain:24048/), click on "Web Application" menu item
In the application list, click on "Deploy"


In the field "Packaged file to be uploaded to the server", select bonita_application/wars/bonita.war
Enter "bonita" as application name
Click on "Ok"


Bonita is now installed on your server.
To access the BUE, click on the "Launch" button in the deployed applications list.

Did you run into problems during the installation, or think this article can be improved ? Let's hear about it in the comments. :-)


Enjoy !

dimanche 6 juin 2010

Installer Bonita sur un serveur Glassfish avec une BDD Oracle

Cet article est également disponible en anglais : How to install Bonita on a Glassfish server with an Oracle database


A l'heure actuelle, la documentation de Bonita ne permet d'installer le runtime et le portail que sur les serveurs JBoss et Tomcat. Avec un peu d'astuce, il est possible de les installer sur un serveur Glassfish.


Présentation de Bonita

Bonita est un moteur de workflow opensource soutenu par la société BonitaSoft.

L'outil "Bonita" est composé de trois éléments :

  • Le Studio Bonita, application autonome qui permet de modéliser graphiquement des processus d'entreprise.
  • Un moteur BPM (le runtime) qui gère toute la logique métier inhérente aux processus (changement d'état, transfert de messages, ...).
  • Un portail, appelé Bonita User Experience (BUE), permettant à chaque utilisateur d'exécuter les processus définis dans le Studio.

Objectif

On se propose d'installer le runtime et la BUE sur un serveur Glassfish v2.1.1. Le runtime devra être interfacé avec une base de données Oracle 10g (XE) hébergée sur une autre machine. Le studio Bonita sera, quand à lui, installé sur le PC d'un administrateur.

Nos utilisateurs se connecteront depuis un poste distant équipé de Windows XP et de Firefox.
L'administrateur utilisera un poste également équipé de Windows XP
Les deux serveurs utilisés (le serveur d'application et le serveur de base de données) seront tous deux sous CentOS 5.5.

Dans ce guide, le serveur d'application répond au nom de domaine bonita.localdomain. Le serveur de base de données répond, quant à lui, au nom de domaine database.localdomain


Note : Le but de ce guide est de présenter l'installation du runtime de manière simple. On ne s'intéressera donc qu'à la configuration du serveur d'application.


Pré-requis

  • Le studio Bonita est déjà installé et utilisable sur le poste administrateur
  • Le SGBD Oracle est opérationnel et une instance de base de données "XE" existe
  • Glassfish est opérationnel sur le serveur d'application
  • Ant est installé sur le serveur d'application

Etape 1 - Exporter le moteur

Démarrer le studio Bonita puis, dans le menu "Processus" cliquer sur "Exporter l'application".

Cocher les cases "Exporter la UserXP" et "Toute la UserXP"
Cocher la case "Exporter le moteur"
Cocher la case "Extraire les librairies des war dans un dossier commun"
Dans la liste des processus, décocher les processus éventuellement sélectionnés.
Choisissez un dossier pour l'export (par exemple : /home/pingtimeout/)

Un fichier bonita_application.zip sera créé dans le dossier spécifié.

Dézipper ce fichier (par exemple dans /home/pingtimeout/bonita_application/), le dossier cible contient les éléments suivants :

  • common-war-lib
  • conf
  • runtime
  • wars
  • INSTALL.txt

Les composants Runtime et UserXP sont maintenant prêts à être installés.


Etape 2 - Création et initialisation des bases de données

Note : dans mon cas, je choisis de stocker les bases de données "core" et "history" sur la même instance de base de données. Il aurait été possible de les séparer sur deux instances distinctes.


Créer deux utilisateurs (CORE et HISTORY) sur l'instance Oracle.

Se rendre dans le dossier bonita_application créé à l'étape précédente et modifier le fichier runtime/conf/hibernate-core.properties afin qu'il contienne les valeurs suivantes :

hibernate.dialect                 org.hibernate.dialect.Oracle10gDialect
hibernate.connection.driver_class oracle.jdbc.OracleDriver
hibernate.connection.url          jdbc:oracle:thin:@database.localdomain:1521:XE
hibernate.connection.username     CORE
hibernate.connection.password     CORE


Modifier le fichier runtime/conf/hibernate-history.properties afin qu'il contienne les valeurs suivantes :

hibernate.dialect                 org.hibernate.dialect.Oracle10gDialect
hibernate.connection.driver_class oracle.jdbc.OracleDriver
hibernate.connection.url          jdbc:oracle:thin:@database.localdomain:1521:XE
hibernate.connection.username     HISTORY
hibernate.connection.password     HISTORY


Ajouter le driver Oracle JDBC dans le dossier runtime/lib/server/


Exécuter la commande suivante :
$ ant init-db
Utiliser la configuration : hibernate-configuration:core


Exécuter la commande suivante :
$ ant init-db
Utiliser la configuration : hibernate-configuration:history


Les bases de données sont créées et initialisées.


Etape 3 - Préparation d'un domaine Glassfish

Note : $GLASSFISH_HOME représente le répertoire d'installation de Glassfish (dans mon cas, il s'agit de /opt/glassfish/)


Créer un domaine "bonita" dans glassfish
$ asadmin create-domain --adminuser admin --portbase 24000 bonita

Saisir un mot de passe pour l'administrateur et un mot de passe de sécurité générale puis valider


Copier tous les fichiers du répertoire bonita_application/common-war-lib/ dans le dossier $GLASSFISH_HOME/domains/bonita/lib/
$ cp bonita_application/common-war-lib/* $GLASSFISH_HOME/domains/bonita/lib/


Copier tous les fichiers du répertoire bonita_application/runtime/lib/server/ dans le dossier $GLASSFISH_HOME/domains/bonita/lib/
$ cp bonita_application/runtime/lib/server/* $GLASSFISH_HOME/domains/bonita/lib/


Copier tous les fichiers du répertoire bonita_application/runtime/conf/ dans le dossier $GLASSFISH_HOME/domains/bonita/config/
$ cp bonita_application/runtime/conf/* $GLASSFISH_HOME/domains/bonita/config/


Démarrer le domaine
$ asadmin start-domain bonita


Le domaine Glassfish est correctement paramétré et il est démarré.


Etape 4 - Installer Bonita sur Glassfish

Dernière étape, il faut maintenant installer le fichier bonita.war sur le serveur d'application.


Se connecter à l'interface d'administration du domaine (dans mon cas, http://bonita.localdomain:24048/)
Dans le menu de gauche, cliquer sur "Application Web".
Dans la liste des applications, cliquer sur le bouton "Déployer"
Saisir "bonita" dans le nom de l'application


Sélectionner le fichier bonita_application/wars/bonita.war dans le champ "Fichier de package à télécharger sur votre serveur"
Cliquer sur le bouton "Ok"


Bonita est maintenant installé sur le serveur.
Pour y accéder, dans la liste des applications web déployées, cliquer sur le lien "Lancer" de la ligne "Bonita".

Des soucis à l'installation ? Des points à améliorer ? N'hésitez pas à laisser un commentaire :-)


Enjoy !