WSO2 ESB - Webapp Deployment Guide [ 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 aproach. It should be the same approach for the 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 from here and extract to a specific location. (E.g.:- /opt/software/wso2esb-2.1.1).

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

  - conf
  - database
  - resources
  - repository
    

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 your favourite 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-2.1.1/resources/security/wso2carbon.jks"
        keystorePass="wso2carbon"/>

Step 4 - Setting environmental variables

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

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

Step 5 - Copying required files to Apache Tomcat

Now create a folder 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-2.1.1/webapps/ROOT/WEB-INF /opt/software/apache-tomcat-5.5.20/webapps/esb/
    

Now, copy the org.wso2.carbon.server-2.0.1.jar in the lib directory of the WSO2 ESB distribution to the lib directory inside the WEB-INF directory which you have already copied into the Tomcat.

E.g.:-
  cp /opt/software/wso2esb-2.1.1/lib/org.wso2.carbon.server-2.0.1.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 correct 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.xml which is in the axis2.xml file located at CARBON_HOME/conf
    conf/synapse.xml
    to
    /opt/software/esb-home/conf/synapse.xml

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