UPDATE: I've sorted out the classpath loading issues regarding the patches.  See the EAR creation section.

I'm editing this original post to update it with the final resolution so all the steps are in one place.

Why Websphere?  Because that is what we run as our standard app server.  Maybe I'll give up if I can't resolve all the issues.   But below is a comprehensive list of steps to get the esb running on Websphere 6.1. 

BUT, I am unable to get to the wso2 esb admin console.  This is where I need help!  I've tried various ports but there is no response, as if the service didn't come up.  I'll follow this post with a log.   RESOLUTION: use the latest build from the wso2 esb.  I tested with 2008-06-29.  There is a fix to the startup servlet.


Deploying wso2 esb to websphere 6.1

First, create an EAR for Websphere:

  1. In RAD 7 create a blank Web App Project and associated EAR: wso2esb, wso2esbEAR
  1. Turn off xml, xsl, and dtd validation in the project properties
  2. Don't try to deploy this to websphere from within RAD!
  3. Unzip the binary distribution of wso2
  4. Import the "webapp" directory into the RAD project WebContent folder, choose overwrite existing resources without warning.
  5. Make sure the classes dir in WEB-INF is empty.  The contents will be in the working dir of the websphere profile.
  6. MOVE the WEB-INF/lib/patches and WEB-INF/lib/endorsed directories to the root of the EAR - these jars must be loaded first by the classloader.
  7. MOVE the WEB-INF/lib contents to a new EAR directory called "esb" (this new directory is helpful to keep the jars organized rather than putting them in the root of the EAR).
  8. Edit the META-INF/MANIFEST.MF to include all the jars in the EAR.  ATTENTION: Make sure the files in the EAR/patches folder are FIRST in the MANIFEST Class-Path so that they will load in the correct order..  Example:

    Manifest-Version: 1.0

    Class-Path: axiom-api-1.2.7-001.jar




    etc... (about 130 more jars listed)
  9. (Optional) Add this file to the wso2esb/src directory (you may need to use the RAD7 resources view to do this):





    This will allow the Log4j to be used for the application rather than the websphere logging

  10. (I am a bit uncertain about this point since all the jars were put in the EAR it may not matter)

    Edit EAR deployment descriptor.  Deployment TAB:
    1. wso2esbEAR classloader mode: PARENT LAST

    2. war classloader policy: MODULE

    3. wso2esb classloader mode: PARENT LAST (to allow patches to load first)
  11. Export the EAR

Then deploy to websphere 6.1

  1. Create WAS 6.1 profile

    Make note of the ports.  They can be found in the profile/config/cells/cellname/nodes/nodename/serverindex.xml  WC_defaulthost, and WC_defaulthost_secure

  2. Set the java temp directory to a unique directory


    There are a few artifacts that are created during runtime which would collide if multiple esbs were run on the same server:

    /tmp/_Axis2    directory

    /tmp/javasharedresources    directory

    /tmp/ep.jacl    empty file
  3. Set property (at least in WAS otherwise you get "Error 403: SRVE0190E: File not found: " errors in the browser (servlet filter is trying to forward to a file that does not exist).  https://www-01.ibm.com/support/docview.wss?uid=swg1PK65408

    Add this to the "Server - Web Container - custom properties" (server.xml) in the <components xmi:type="applicationserver.webcontainer:WebContainer"

    <properties xmi:id="Property_1213963315728" name="com.ibm.ws.webcontainer.invokefilterscompatibility" value="true" description="To make the filter invoke on a request without a servlet mapping" required="false"/>
  4. Create a working directory somewhere and configure Websphere JVM to use it.

    For this example it will exist under the profile dir aka. USER_INSTALL_ROOT, and we'll call it WorkingDir

     <processDefinitions xmi:type="processexec:JavaProcessDef" xmi:id="JavaProcessDef_1212583346049" workingDirectory="${USER_INSTALL_ROOT}/WorkingDir" executableTargetKind="JAVA_CLASS" executableTarget="com.ibm.ws.runtime.WsServer">
  5. Create a sub dir in WorkingDir called webapp and create these directories in it:
    1. logs for Log4j
    2. derby for new derby distribution
  6. Unzip the binary distribution for wso2 esb to a temporary dir
  7. Copy these dires from the unzipped distribution to the WorkingDir
    1. registry
    2. repository
    3. samples
    4. webapp
  8. In the webapp REMOVE THE webapp/WEB-INF/lib dir to save space.  The jars are all in the EAR created above (about 130!).
  9. Change the working directory of the Websphere 6.1 server to the newly created WorkingDir above

    server.xml example.  This puts the working directory just under the WAS Profile dir in a dir called WorkingDir:

    <processDefinitions xmi:type="processexec:JavaProcessDef" xmi:id="JavaProcessDef_1212583346049" workingDirectory="${USER_INSTALL_ROOT}/WorkingDir" executableTargetKind="JAVA_CLASS" executableTarget="com.ibm.ws.runtime.WsServer">
  10. Change the server.xml to include the /WorkingDir/webapp/WEB-INF/classes dir

    <classpath><absolute path>/WorkingDir/webapp/WEB-INF/classes</classpath>

    Specifically the Hibernate configuration must be in the class path as

  11. Configure log4j

    Set JVM property
    1.       <systemProperties xmi:id="Property_1213125579199" name="log4j.configuration" value="file:webapp/WEB-INF/classes/conf/log4j.properties" required="false"/>
  12. (optional) Websphere comes installed with Derby in the root (Websphere/Derby).  This is common across ALL websphere profiles. 

    One option is to use the existing Websphere derby started by websphere.  To do that, change this server.xml configuration to false:


    Option two is to set up Derby to run in the profile/server JVM with independent settings and database directories
    1. Create dir WorkingDir/derby
    2. Copy the wso2esb-1.7/webapp/WEB-INF/classes/conf/derby.properties file to WorkingDir/derby
    3. Change these properties as desired:
      1. derby.drda.portNumber=21528
      2. derby.drda.traceDirectory=../logs
      3. derby.stream.error.file=../logs/derby.log
      4. derby.infolog.append=true
    4. Add the following system property to the JVM to point to the new "derby home" dir:

      1. <systemProperties xmi:id="Property_1213112824074" name="derby.system.home" value="<absolute location>/WorkingDir/derby" required="false"/>
  13. Configure AXIS
    1. This config file is located by path relative to the working dir


      but can be overridden by the JVM property
      1. <systemProperties xmi:id="Property_1213125304168" name="axis2.xml" value="webapp/WEB-INF/classes/conf/axis2.xml" required="false"/>
      2. <systemProperties xmi:id="Property_1213125318433" name="axis2.repo" value="repository" required="false"/>

    2. axis2.xml configurations relate mostly to ports:
      1. <transportReceiver name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener">

               <parameter name="port" locked="false">28080</parameter>

               <parameter name="non-blocking" locked="false">true</parameter>

      2. <transportReceiver name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener">

               <parameter name="port" locked="false">28443</parameter>

               <parameter name="non-blocking" locked="false">true</parameter>
      3. <transportReceiver name="admin/https" class="org.wso2.esb.transport.tomcat.HttpsTransportListener">

               <parameter name="port" locked="false">29443</parameter>

               <!--<parameter name="non-blocking" locked="false">true</parameter>-->

      4. KeyStore/Location should be absolute paths.  There are four of them:

        <Location>{put your absolute path here to working dir}/webapp/WEB-INF/classes/conf/identity.jks</Location>
  14. Configure Hibernate

    NOTE: configuration in classpath set above located WorkingDir/webapp/WEB-INF/classes/conf/wso2esb.hibernate.cfg.xml

    The wso2esb.hibernate.cfg.xml configuration is mostly related to the derby config above:

    <property name="connection.url">jdbc:derby://localhost:21528/database/WSO2ESB_DATABASE;create=true</property>
  15. Configure Apache Synapse


    There may be some port information in it
    1. <systemProperties xmi:id="Property_1212779662857" name="synapse.xml" value="<absolute path>/webapp/WEB-INF/classes/conf/synapse.xml" required="false"/>
  16. Configure wso2 esb
    1. Set the JVM property esb.home to the WorkingDir that contains all the directories from the binary distrubution above.

    2.      <systemProperties xmi:id="Property_1212592993985" name="esb.home" value="<absolute path>/WorkingDir" description="pk set for wso2" required="false"/>
    3. (optional) Config file location can be overridden by the esb.xml JVM Property

    4. esb.xml=webapp/WEB-INF/classes/conf/server.xml
    5. Properties to change for port configuration:
      1. <Ports.JMX>21099</Ports.JMX>
      2. <AdminConsole><Port>9463</Port>  <!-- this MUST be the secure port for the Websphere App server ! -->
      3. <RMIRegistryPort>21099</RMIRegistryPort>     <!-- RMI Registry port used for JMX -->
      4. <HTTPPort>28280</HTTPPort>                   <!-- HTTP port used by the underlying Axis2/Synapse -->
      5. <HTTPSPort>28243</HTTPSPort>                 <!-- HTTPS port used by the underlying Axis2/Synapse -->
      6. <DerbyPort>21528</DerbyPort>                 <!-- Derby database port -->
  17. NOTE: This is not sued in wso2 esb 1.7! Configure wso2 esb admin console javascript:
    1. WorkingDir/webapp/js/main.js

      var httpsPort = 29443;   <<<---- this port should be the same as the <AdminConsole><Port>?
  18. Configure wso2 esb repository
    1. WorkingDir/webapp/WEB-INF/classes/conf/registry.xml
    2. Change the port for derby

  19. Install wso2esbEAR created in RAD7 Link
  20. Restart Websphere
  21. Look in the WorkingDir/logs for the following files:
    1. derby.log - derby service
    2. esb_service.log
    3. esb_trace.log
    4. wso2-esb.log
    5. NOTE: the SystemOut.log from Websphere will include some esb logging, especially if you use the Websphere logger rather than Log4j (see above)
  22. Access the wso2 esb admin console (you must use the secure port):



NOTE: we prefer to use the older file based registry rather than the embedded wso2 database registry.  To do that we configured the synapse.xml as follows:

<syn:registry provider="org.wso2.esb.registry.ESBRegistry">       

<syn:parameter name="root">file:registry/</syn:parameter>       

<syn:parameter name="cachableDuration">15000</syn:parameter>   


This reduces the need for derby a bit, eliminating one database.