How to deploy WSO2 ESB-3.X on Apache Tomcat

WSO2 DOES NOT ENCOURAGE INSTALLING WSO2 ESB ON TOP OF OTHER APPLICATION SERVERS. WSO2 HAS DECIDED TO DROP SUPPORT FOR WEBAPP DEPLOYMENT MODE OF THE WSO2 PLATFORM AND PRODUCTS.

I have noticed a lot of different articles, blog posts with instructions on deploying WSO2 ESB on Apache tomcat. But I observed that most of them are obsolete and the guidelines are not applicable for the latest ESB versions. Therefore, I thought to put together the steps of setting up WSO2 ESB-3.X versions on Apache Tomcat-6.X

Step 1:

Download WSO2 ESB-3.X. Extract the downloaded zip and copy repository and resources directories in to a new folder. Say it is esb-repo (i.e:- /home/user/esb-repo)

Step 2:

Lets refer to your tomcat installation directory, CATALINA_HOME. Go to CATALINA_HOME\webapps directory and create a new directory, esb.

Now, copy wso2esb-3.0.0\webapps\ROOT\WEB-INF to CATALINA_HOME\webapps\esb

Also, copy wso2esb-3.0.0\lib\log4.properties file to CATALINA_HOME\webapps\esb\WEB-INF\classes

Step 3:

Next, we need to enable https in tomcat. Therefore, edit CATALINA_HOME\conf\server.xml by adding the following entry.

<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

enableLookups="false" disableUploadTimeout="true"

acceptCount="100" scheme="https" secure="true" SSLEnabled="true"

clientAuth="false" sslProtocol="TLS"

keystoreFile = "/home/user/esb-repo/resources/security/wso2carbon.jks"

keystorePass="wso2carbon"/>

Make sure to give the exact location of wso2carbon.jks as highlighted above.

Step 4

We have done the configurations required in tomcat. Now, we must do the necessary configurations in a set of config files shipped with WSO2 ESB. We will update carbon.xml, axis2.xml, registry.xml and user-mgt.xml which can be found at esb-repo/repository/conf directory.

First, open carbon.xml and update the ServerURL element as follows.

<ServerURL>https://localhost:8443/esb/services/</ServerURL>

Note that we have configured tomcat to run on 8443 port.

When we deploy ESB on an application server, it uses the http/https transport provided by the servlet container when communicating with registry. Therefore, we must update the registry HTTP port in carbon.xml. In order to do that, uncomment and update the following element in carbon.xml.

<RegistryHttpPort>8080</RegistryHttpPort>

Thats all we need to update in carbon.xml, save and close the file.

Next, open registry.xml and update DB URL as follows.

<url>jdbc:h2:/home/user/esb-repo/repository/database/WSO2CARBON_DB</url>

Now, open user-mgt.xml and update user management database URL as follows.

<Property name='url'>jdbc:h2:/home/user/esb-repo/repository/database/WSO2CARBON_DB</Property>

Make sure to specify the absolute path of the WSO2CARBON_DB in both of the above elements.

Next, we need to configure a few elements in esb-repo/repository/conf/axis2.xml file.

Locate NIO HTTPS transport listener (HttpCoreNIOSSLListener) element and specify the absolute path of keystore and truststore locations as follows.

<KeyStore>

<Location>/home/user/esb-repo/resources/security/wso2carbon.jks</Location>

<TrustStore>

<Location>/home/user/esb-repo/resources/security/client-truststore.jks</Location>

Similarly update the keystore and trustore paths of NIO HTTPS transport sender (HttpCoreNIOSSLSender)

We should also specify the absolute path of synapse-config directory as follows.

<parameter name='SynapseConfig.ConfigurationFile' locked='false'>/home/charitha/products/esb/esb-repo/repository/conf/synapse-config</parameter>

Step 5

We have almost completed the required configurations. Now, open a new shell and change the directory to CATALINA_HOME/bin.

Define an environment variable called CARBON_HOME and set the path to your esb-repo directory.

In windows; set CARBON_HOME=C:\esbs\esb-repo

In linux; export CARBON_HOME=\home\user\esb-repo

Start tomcat from the same command window/shell.

catalina.sh run

WSO2 ESB will be started successfully. You can access the management console using https:\\localhost:8443\esb\carbon

Thats all! You could follow the above steps and deploy WSO2 ESB-3.X on Tomcat successfully. If you do not like to follow each of the above steps manually, I have written a ruby script to automate the above procedure and install ESB on tomcat. You can download it from here

You just need to specify three directory paths there in esb3.X_tomcat_install_linux.rb and rest of the installation steps will be done automatically by the script.

esb_repo = Any directory in the local file system

CARBON_BIN_HOME= Home directory of ESB binary distribution

CATALINA_HOME= Home directory of the tomcat binary