[ Deployment Guide ]

WSO2 Enterprise Service Bus (ESB) Webapp Deployment Guide

WSO2 ESB can be deployed on different application servers such as IBM WebSphere, BEA WebLogic Server, JBoss and Apache Tomcat. This guide describes how to deploy the ESB on Apache Tomcat in a step-by-step manner. The methodology should be the same for other application server deployments as well, but it will require some knowledge on the application server for you to get it working on that particular application server.

Step 1 - Downloading and installing Apache Tomcat

You can download the latest version of Apache Tomcat from here (We will be using Apache Tomcat 5.5.20 to demonstrate this particular deployment). Extract the downloaded distribution to a specific location and define the environment variables properly. (Assume you extracted the downloaded Tomcat into the folder \opt\software\apache-tomcat-5.5.20) 

E.g.: -
    CATALINA_HOME=\opt\software\apache-tomcat-5.5.20

Step 2 - Downloading and installing WSO2 ESB

Download the WSO2 ESB distribution and extract to a specific location in the file system. (E.g.:- /opt/software/wso2esb-4.0.0).

Copy the repository in the extracted distribution to a different location (this is the directory we are planning to treat as ESB_HOME, E.g.:- /opt/software/esb-home)

Step 3 - Enable HTTPS on the Apache Tomcat

Next you will need to enable HTTPS on Apache Tomcat since WSO2 ESB administration console runs over HTTPS. To do this, open up the server.xml file located at $CATALINA_HOME/conf using a text editor and uncomment the following: 

  <Connector port="8443" maxHttpHeaderSize="8192"
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
        enableLookups="false" disableUploadTimeout="true"
        acceptCount="100" scheme="https" secure="true"
        clientAuth="false" sslProtocol="TLS"/>

Then you will need to provide the keystore file location along with it's password as below. 

  <Connector port="8443" maxHttpHeaderSize="8192"
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
        enableLookups="false" disableUploadTimeout="true"
        acceptCount="100" scheme="https" secure="true"
        clientAuth="false" sslProtocol="TLS"
        keystoreFile = "/opt/software/wso2esb-3.0.1/resources/security/wso2carbon.jks"
        keystorePass="wso2carbon"/>

Step 4 - Setting environment variables

You will have to set an environment variable with the name CARBON_HOME pointing it to the directory into which you have copied the repository directory. 

E.g.:-
    CARBON_HOME=/opt/software/esb-home

Step 5 - Copying required files to Apache Tomcat

Now create a new directory inside the webapps folder of Tomcat.

E.g.:-
    /opt/software/apache-tomcat-5.5.20/webapps/esb

Next, you need to copy the WEB-INF folder of the extracted distribution of the ESB to the created webapp directory. 

E.g.:-
  cp -r /opt/software/wso2esb-4.0.0/lib/core/WEB-INF /opt/software/apache-tomcat-5.5.20/webapps/esb/

You should also copy all the jar files in lib/api directory of ESB distribution into the WEB-INF/lib directory of the ESB webapp in Tomcat. 

E.g.:-
  cp /opt/software/wso2esb-4.0.0/lib/api/*.jar /opt/software/apache-tomcat-5.5.20/webapps/esb/WEB-INF/lib

Step 6 - Configuring the WSO2 ESB

  1. Open the carbon.xml file which is in the CARBON_HOME/conf folder and specify the following URL as the ServerURL https://localhost:8443/esb/services/
  2. Then you need to specify the absolute paths of the WSO2CARBON_DB of the two files registry.xml and user-mgt.xml 
    jdbc:derby:database/WSO2CARBON_DB;create=true
    has to be replaced with 
    jdbc:derby:/opt/software/esb-home/WSO2CARBON_DB;create=true
  3. In order for the logging to work properly you need to copy the log4j.properties file found at the lib directory of the extracted distribution to the webapp classpath
  4. You need to specify the absolute paths for the two .jks files wso2carbon.jks and client-truststore.jks specified in the HTTPS transport configuration section of the axis2.xml and also the wso2carbon.jks file specified in the carbon.xml file.
  5. Further, you need to uncomment the wsdlEPRPrefix parameter of the HTTP and HTTPS transport receiver configurations and put the value as 
    http://${host}:${port}/services
  6. Finally you will have to specify the absolute path of the Synapse configuration files in the axis2.xml file located at CARBON_HOME/repository/conf. Simply change, 
    repository/deployment/server/synapse-config/default
    to 
    /opt/software/esb-home/repository/deployment/server/synapse-config/default

Step 7 - Starting the Apache Tomcat Server

Now you can start the Apache Tomcat server by giving the command from the tomcat installation bin directory

  ./catalina.sh run

Step 7 - Login to the WSO2 ESB Administration Console

Now you should be able to login to the WSO2 ESB Administration Console as,

  https://localhost:8443/esb/carbon

Specific Instructions when Deploying WSO2 ESB in Other Application Servers

JBoss

  1. In [Step-5], You should skip copying jboss-transaction-api-1.0.1.GA.jar when copying jars from /opt/software/wso2esb-4.0.0/lib/api/ to /opt/software/apache-tomcat-5.5.20/webapps/esb/WEB-INF/lib
  2. Delete /opt/software/esb-home/repository//components/plugins/geronimo-jta_1.1_spec-1.1.0.wso2v1.jar

Without following these two steps, Transaction Mediator will not work when WSO2 ESB deployed in JBoss