WSO2 BPS - Installation Guide -

Installation Guide

Table of Content


WSO2 Business Process Server (BPS) Installation Guide

This document describes how to install and run WSO2 Business Process Server using binary distribution available fordownload. Binary Distribution includes binary files for both MS Windows and Linux operating systems as a zip file.

Installing and Running WSO2 BPS using the binary distribution

Prerequisites

Java SE Development Kit 1.6.x (For instructions on setting up the JDK on different operating systems, visithttp://java.sun.com)

To build WSO2 BPS from the Source distribution, it is necessary that you have JDK 1.6.x version and Maven 2.2.0 or later

Web browser- To log-in to the BPS Management Console Mozilla Firefox or Google Chrome at a resolution of 1024x768 or higher is recommended. MS Internet Explorer 7 or 8 can be used as well, with some limitations. Once the WSO2 BPS is started point the browser to https://localhost:9443/carbon you can access your Management Console.
Memory No minimum requirement - A heap size of 256~512MB is generally sufficient to process typical SOAP messages. Requirements may vary with larger message size and on the number of messages processed concurrently
Disk No minimum requirement. The installation will require ~150MB excluding space allocated for log files and Databases.
Operating System Linux, Solaris, MS Windows - XP/ Vista (Not fully tested on Windows Vista). As the WSO2 BPS is a Java application, it will generally be possible to run it on other operating systems with a JDK 1.6.x runtime. Linux/Solaris is recommended for a production deployment.


Installing on Linux / Unix

  1. Download the WSO2 BPS binary distribution.
  2. Extract the zip archive where you want the WSO2 BPS installed (e.g. into /opt)
  3. Set the JAVA_HOME environment variable to your Java home using the export command or by editing /etc/profile, and add the Java /bin directory to your PATH
  4. Execute the WSO2 BPS start script from the bin directory. e.g. ./wso2server.sh OR ./wso2server.sh start
  5. Check your WSO2 BPS instance using the URL https://localhost:9443/carbon which will take you to the WSO2 BPS Management Console.
  6. Login as "admin" using the default password "admin"

Installing on MS Windows

The following steps will take you through the installation for the MS Windows operating system.

  1. Download the WSO2 BPS binary distribution.
  2. Extract the zip archive where you want the WSO2 BPS installed
  3. Set the JAVA_HOME environment variable to your Java installation, and the PATH environment variable to the Java /bin directory.
  4. Execute the WSO2 BPS start script from the bin folder. e.g. wso2server.bat
  5. If you would like to install the WSO2 BPS as a Windows service, use the install.bat script
  6. Check your WSO2 BPS instance using the URL https://localhost:9443/carbon which will take you to the WSO2 BPS Management Console.
  7. Login as "admin" using the default password "admin"


Installing WSO2 CS

WSO2 Carbon Studio provides the tooling environment for users to model, deploy and execute the WS-BPEL processes. Latest WSO2 Carbon Studio documentation is available here. Please follow the installation guide in above documentation to install WSO2 Carbon Studio.


Configure WSO2 BPS with external data sources

WSO2 Business Process Server comes with a embedded H2 database as the BPEL engine persistence storage. Embedded databases are not suitable as the BPEL engine persistence storage for production deployments.This document will guide you through the steps to configure WSO2 BPS with external database servers.


Table of Contents


Setting up Database Server

WSO2 BPS uses Apache ODE as it's BPEL engine and Apache ODE can be configured to use external database other than the embedded H2 databse as it's persistence storage. First you must create a database in your preferred database server and load the database schemas provided to that database.

  1. Set up and start your database server.
  2. Create a database.
  3. Load the BPS schema into that database using provided SQL scripts. For example if you are using Oracle as your databse server, use oracle.sql script located inside 'dbscripts/bps' directory to create the BPS schema.

Configuring a Data Source

Definition of the reusable database sources can be done using datasources.properties file located inside WSO2 BPS 'repository/conf' directory under BPS root directory. It is possible to configure any number of data sources. But for WSO2 BPS one data source is enough.

WSO2 BPS ships with a default datasources.properties file which contains configurations for embedded H2 database. To configure a external database you only need to change following properties which are database specific. 

            synapse.datasources.bpsds.driverClassName=net.sourceforge.jtds.jdbc.Driver
            synapse.datasources.bpsds.url=jdbc:jtds:sqlserver://192.168.1.2:1433/bps
            synapse.datasources.bpsds.username=sa
            synapse.datasources.bpsds.password=root123

You can fine tune your data source configurations using various other properties available. You can find description about other configuration in parameters document from Apache Commons. WSO2 BPS data sources support all the parameters support by Apache dbcp and you must follow the synapse.datasources.<data source name>.<parameter>=<parameter value> pattern when specifying parameters for the data source. You can use any of the parameters supported by Apache dbcp to replace 'parameters' field.


Note: For embedded H2 database, if absolute file URL is used for the datasource URL on Windows environment, that needs to be configured as follows. (i.e. the backslashes should be escaped) synapse.datasources.bpsds.url=jdbc:h2:file:C:\\bps\\myDs

Configure JNDIProviderPort to run multiple server instances.

The datasources.properties contains following property which requires to change when configuring to run multiple server instances. 

            synapse.datasources.providerPort=2199

The following two approaches use the advantage of port-offsetting to automatically alter this property value without manually changing datasources.properties or bps.xml.

Method 1: Uncomment following section in carbon.xml
        <Ports>
		<!-- 
             	Override datasources JNDIProviderPort defined in bps.xml and datasources.properties files
		-->
			<!--<JNDIProviderPort>2199< /JNDIProviderPort>-->
	</Ports>

JNDIProviderPort has been overridden in carbon.xml and can be enabled by uncommenting above. Therefore, it is not required to change RMI ports in multiple places as defined in bps.xml and datasource.properties files.

Method 2: Without enabling above property in Method 1.

This only requires to change port offset value in carbon.xml. Then it will automatically alter the JNDI ports defined in bps.xml and datasources.xml. This won't require to enable/uncomment above section in Method 1.


Registry Configuration

You must leave Registry configuration in bps.xml as it is. If you want to configure registry to use external data base you must follow the registry configuration document.


Configure OpenJPA specific properties

You can configure and fine tune OpenJPA by specifying OpenJPA properties in BPS_HOME/repository/conf/bps.xml file. 

<tns:WSO2BPSxmlns:tns="http://wso2.org/bps/config">
    ...
    <tns:OpenJPAConfig><tns:propertyname="openjpa.FlushBeforeQueries"value="true"/><tns:propertyname="property name"value="value"/>
        ...
    </tns:OpenJPAConfig>
    ...
</tns:WSO2BPS>


Configure Multi Threaded HTTP Connection Manager

HTTP connection manager should be configured to be sync with the concurrent HTTP connections that should be in the BPS server. 

<tns:WSO2BPSxmlns:tns="http://wso2.org/bps/config">
    ...
    <tns:MultithreadedHttpConnectionManagerConfig><tns:maxConnectionsPerHostvalue="20"/><tns:maxTotalConnectionsvalue="200"/></tns:MultithreadedHttpConnectionManagerConfig>
    ...
</tns:WSO2BPS>