Installing and Configuring the ActiveBPEL Engine



This document describes how to install the ActiveBPEL engine.


Dependencies
============

The ActiveBPEL engine requires an installed and properly configured servlet
container. It has been tested with Tomcat. The installation scripts that come
with the ActiveBPEL engine use the environment variable CATALINA_HOME, which
defines the top-level Tomcat directory. The ActiveBPEL engine should run under
any standard servlet container.

You may download Tomcat from the Tomcat Web site
(http://jakarta.apache.org/tomcat) or from the ActiveBPEL download page
(http://www.activebpel.org/download).


Downloading the Software
========================

Download the most recent version of the ActiveBPEL engine from the ActiveBPEL
download page (http://www.activebpel.org/download). You will have a choice of
downloading either a .tar.gz file or a .zip file. Both archives contain the
same files. The name of the archive will be activebpel-version-type.tar.gz or
activebpel-version-type.zip. "Version" is a version number like "1.0.1".
"Type" is one of "src" (source), "bin" (binaries), or "all" (source and
binaries).

Extract the distribution from the archive using your favorite command line or
GUI tool. Doing so will create a directory named activebpel-version. You may
create, rename, or move this directory anywhere you wish. For the rest of this
document, we will simplly call this directory "activebpel".


Installing the ActiveBPEL Engine
================================

Run the script install.bat (Windows) or install.sh (Unix). It copies the
contents of lib into $CATALINA_HOME/shared/lib and creates the directory
$CATALINA_HOME/bpr, where BPEL process .bpr archives are deployed.

Windows:

    C:\> cd \activebpel
    C:\activebpel> install.bat

Unix:

    % cd activebpel
    activebpel% install.sh

When running install.sh on Unix, you may need root privileges.


Changing Engine Configuration Parameters
----------------------------------------

There are a few server parameters that are configurable via a small XML file
named aeEngineConfig.xml, which is is found in the directory
$CATALINA_HOME/bpr. Configuration changes made via the BpelAdmin configuration
page, normally found at http://localhost:8080/BpelAdmin/config.jsp, are saved
to this file.

Online help about engine configuration is available by clicking the "Help"
link at the bottom of the left-side menu on every BpelAdmin page.


Deploying Your BPEL Process
===========================

See "Deploying BPEL Processes" (deploy_bpel.txt).

If the ActiveBPEL engine is running, soon after you deploy your BPEL process
the ActiveBPEL engine will notice the .bpr file and read it. Your BPEL process
is ready to use.


Starting the ActiveBPEL Engine
==============================

To start the ActiveBPEL engine, start your servlet container.


Windows:

    C:> %CATALINA_HOME%\bin\startup.bat

Unix:

    % $CATALINA_HOME/bin/startup.sh

When running startup.sh on Unix, you may need root privileges.

Stopping the Engine
-------------------

To stop the ActiveBPEL engine, stop your servlet container.


Windows:

    C:\> %CATALINA_HOME%\bin\shutdown.bat

Unix:

    % $CATALINA_HOME/bin/shutdown.sh

When running shutdown.sh on Unix, you may need root privileges.


Engine Status Information
=========================

When the servlet engine (for example, Tomcat) is running, there are two Web
pages available that display information about the server: the Axis Web
services listing and the ActiveBPEL engine admistration page.

    Axis Web Services Listing
    -------------------------

    The page at http://localhost:8080/active-bpel/services is generated by
    Axis (modify the host and port to suit your installation). It lists all of
    the Web services that are available. This list is independent of the
    ActiveBPEL engine; the engine hands Web services to Axis to deploy. Each
    service lists its available operations and has a "wsdl" link next to its
    name. Clicking on that link causes Axis to generate the WSDL for that Web
    service and send it to your browser. (If your browser does not display
    anything, then you can use your browser's "Save Link As..." feature to
    save the WSDL to your computer and look at it that way.) The format for
    each WSDL link is .../services/ServiceName?wsdl so you can type the link
    in directly if you desire.

    ActiveBPEL Engine Adminstration
    -------------------------------

    The Web page at http://localhost:8080/BpelAdmin/ is the ActiveBPEL engine
    adminstration page (again, modify the host and port to suit your
    installation). From that page you can see and edit the engine's
    configuration parameters and click the links on the left to see
    information about the deployed and active BPEL processes.

    The engine configuration parameters are described in the online help
    available from the BpelAdmin pages.

    Clicking on "Deployed Processes" displays a list of the BPEL processes
    deployed within the engine.

    Clicking on "Active Processes" displays by default a list of the BPEL
    processes that are running, have completed, or faulted. Click on "Running"
    or "Complete" in "Process Filter Selections" to limit the process display
    to those states.

    Clicking on "Receive Queue" displays a list of queued receives.


Troubleshooting
===============

Debugging and Logging
---------------------

Tomcat writes its log files to the directory $CATALINA_HOME/logs (under
Windows, %CATALINA_HOME%\logs).


For information about ActiveBPEL engine logging, see "Debugging and Logging"
in the architecture document.