Running WSO2 Carbon-3.0.1 based products on IBM WebSphere 6.1

We will refer to the below WSO2 Carbon-3.0.1 based products as WSO2 Products in this tutorial.  Also, the location of the file system where you extract the binary distributions of any of the above products will be referred to as WSO2_PRODUCT_HOME.

Applies To 

Table of Contents

5.1 WSO2 ESB Configurations
5.2 WSO2 Identity Server Configurations

1. Preparing WebSphere

First, create a new profile in WebSphere so that we can isolate the WSO2 product deployment from the others. Then, set up a new profile by invoking the WebSphere profile management tool. For our purposes, let's assume the new profile directory name is wso2profile (e.g:- C:\Program Files\IBM\WebSphere\AppServer\profiles\wso2profile).

Access the newly created WebSphere profile directory and start the server (go to C:\Program Files\IBM\WebSphere\AppServer\profiles\wso2profile\bin and run startServer.bat).

startServer.bat server1 

2. Building a deployable artifact

Next, build a deployable artifact from the WSO2 product binary distribution so that it can be deployed on the WebSphere server. Download any of the above WSO2 Carbon-3.0.1 based products from wso2.org/downloads. Extract the downloaded .zip into a directory (WSO2_PRODUCT_HOME). Copy repository and resources directories into a new folder. Hereafter, refer to this new directory as wso2-repo, i.e. C:\wso2\wso2-repo.

Also, create a .war file, wso2.war, by including the WEB-INF directory located at the webapps\ROOT directory of WSO2_PRODUCT_HOME. Now, your wso2-repo should have the following contents:

- repository

- resources

- wso2.war

The contents of the wso2.war will be;

Point to the created wso2.war during the installation process. In order to enable WSO2 Carbon logging inside WebSphere, copy log4j.properties file in WSO2_PRODUCT_HOME\lib directory to wso2.war\WEB-INF\classes. 

3. Configuring SSL on WebSphere

Enable SSL in WebSphere server since the interactions with the WSO2 server will happen through HTTPS. Login to WebSphere administration console (username and password should have been configured for admin console when creating a WebSphere profile). Click on Security in the left menu and select SSL certificate and key management.

Click on the Key stores and certificates link in the above screen. Click on New to define a new keystore. Enter the following values for the general keystore properties given in the page:

Name: wso2carbon_ks (unique name to identify the keystore)

path: C:\wso2\wso2-repo\resources\security\wso2carbon.jks

password: wso2carbon

Type: JKS

Save the configuration. The new keystore will be shown as follows:

Now, click on the SSL configurations link from the SSL certificates and keystore management page. Click on NodeDefaultSSLSettings. Select wso2carbon_ks as trust store name and keystore name. 

Also select wso2carbon as default server certificate alias and default client certificate alias. Click Apply to save the settings. Now, the necessary changes to enable SSL on WebSphere have been configured. Continue with deploying the WSO2 product on WebSphere. 

4. Updating WSO2 Product Configuration Files

WSO2 Carbon based products are provided with a set of configuration files in WSO2_PRODUCT_HOME/repository/conf directory, which can be used to update the ports, database settings, web application context roots, etc. Update carbon.xml, axis2.xml, registry.xml and user-mgt.xml which can be found at the above wso2-repo\repository\conf directory.

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

<ServerURL>https://localhost:9444/wso2/services/</ServerURL> 

Note that WebSphere has been configured to run on 9444 HTTPS port.
To deploy the WSO2 product on the WebSphere server on non-root webContext, update the WebContextRoot element as follows:

<WebContextRoot>/wso2</WebContextRoot>

Save and close carbon.xml.
Open registry.xml and update the database URL as follows:

<url>jdbc:h2:C:\wso2\wso2-repo\repository\database\WSO2CARBON_DB;create=true</url> 

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

<url>jdbc:h2:C:\wso2\wso2-repo\repository\database\WSO2CARBON_DB;create=true</url>  

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

Change the HTTP and HTTPS ports in Transports section of axis2.xml as follows:

Please note, this particular configuration is not applicable for the WSO2 ESB.

<transportReceiver name="http" class="org.wso2.carbon.core.transports.http.HttpTransportListener"> 
 <parameter name="port">9081</parameter> </transportReceiver> 
 <transportReceiver name="https" class="org.wso2.carbon.core.transports.http.HttpsTransportListener">   
 <parameter name="port">9444</parameter> </transportReceiver> 

5. WSO2 ESB and WSO2 Identity Server Specific Configurations

NOTE:- This section applies only if you are configuring the WSO2 ESB or the WSO2 Identity Server. If you are using any other product, skip to step 6.

5.1 WSO2 ESB configurations

If you install the WSO2 ESB on WebSphere, you should specify the absolute path of the synapse configuration file in axis2.xml as follows:

<parameter name='SynapseConfig.ConfigurationFile' locked='false'>C:\wso2\wso2-repo\repository\conf\synapse-config</parameter>

Due to the NIO NHTTP transport used in WSO2 ESB, the non blocking HTTP transport sender and receiver should be updated in axis2.xml as follows:

<transportReceiver name='http' class='org.apache.synapse.transport.nhttp.HttpCoreNIOListener'>      
   <parameter name='port' locked='false'>8280</parameter>          <parameter name='non-blocking' locked='false'>true<  
    <!-- the non blocking https transport based on HttpCore + SSL-NIO extensions -->  
 <   <transportReceiver name='https' class='org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener'>     
     <parameter name='port' locked='false'>8243</parameter>       
   <parameter name='non-blocking' locked='false'>true</parameter>    
      <!--parameter name="bind-address" locked="false">hostname or IP address</parameter-->   
       <!--parameter name="WSDLEPRPrefix" locked="false">https://apachehost:port/somepath</parameter-->     
     <parameter name='keystore' locked='false'>    
    <KeyStore> <Location>C:\wso2\wso2-repo\resources\security\wso2carbon.jkswso2carbon</Password>  
   <KeyPassword>wso2carbon</KeyPassword>     </KeyStore> </parameter>  
   <parameter name='truststore' locked='false'>    <TrustStore><Location>C:\wso2\wso2-repo\resources\security\client-truststore.jks</Location> 
  <Type>JKS</Type><Password>wso2carbon</Password>  </TrustStore></parameter> 
 <!--<parameter name="SSLVerifyClient">require</parameter>             supports optional|require or defaults to none -->     </transportReceiver>

  <!-- the non-blocking http transport based on HttpCore + NIO extensions -->    
   <transportSender name='http' class='org.apache.synapse.transport.nhttp.HttpCoreNIOSender'>      
    <parameter name='non-blocking' locked='false'>true</parameter>      </transportSender>   
   <transportSender name='https' class='org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender'>      
     <parameter name='non-blocking' locked='false'>true</parameter>        
   <parameter name='keystore' locked='false'> <KeyStore><Location>C:\wso2\wso2-repo\resources\security\wso2carbon.jks</Location>   
  <Type>JKS</Type> <Password>wso2carbon</Password>
 <KeyPassword>wso2carbon</KeyPassword></KeyStore>       </parameter> 
 <parameter name='truststore' locked='false'> <TrustStore> 
 <Location>C:\wso2\wso2-repo\resources\security\client-truststore.jks</Location>  
 <Type>JKS</Type> <Password>wso2carbon</Password> </TrustStore> </parameter>     
      <!-- <parameter name="HostnameVerifier">DefaultAndLocalhost</parameter>-->               <!--supports Strict|AllowAll|DefaultAndLocalhost or the default if none specified -->     </transportSender>

 Here, you must specify the absolute paths of the keystore and trustore locations used in both the NIO HTTPS sender and receiver.

5.2 WSO2 Identity Server Configurations

If you install the WSO2 Identity Server on WebSphere, you should update OpenIDServerUrl and OpenIDUserPattern elements in identity.xml which can be found at wso2-repo/reporsitory/conf. Make sure to update the URLs according to the HTTPS ports configured for WebSphere

<OpenIDServerUrl>https://localhost:9444/is/openidserver</OpenIDServerUrl> <OpenIDUserPattern>https://localhost:9444/is/openid/</OpenIDUserPattern>

6. Installing the WSO2 Product on WebSphere

The required configurations have been completed and, now, the WSO2 product is ready to be deployed on WebSphere.

First, stop the WebSphere server instance if it is still running.

Open a new command window (or shell) and change the directory to C:\Program Files\IBM\WebSphere\AppServer\profiles\wso2profile\bin.

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

In MS Windows; set CARBON_HOME=C:\wso2\wso2-repo.

In Linux; export CARBON_HOME=/home/user/wso2/wso2-repo.

Run startServer.cmd server1

Once the server has started successfully, login to websphere administration console using https://localhost:9044/admin.

Then, go to the Enterprise Applications page and select Install.

Browse the file path of wso2.war which had been created in step 2. Make sure to specify /wso2 as the Context root. Click on Next to proceed through the wizard. Proceed with accepting the default values in the rest of the steps in the installation wizard. Finally, click on Finish to deploy the application.

If the deployment is successful, save the configuration. wso2_war will be shown under the Enterprise Applications list as follows:

Select wso2_war and click on Start to start the WSO2 Carbon based product on WebSphere. If it is successful, the application status will be marked in green to represent success.

Now, the WSO2 Carbon management console will be accessible using https://localhost:9444/wso2/carbon.

Author

Charitha Kankanamge

Senior Technical Lead and Manager - Quality Assurance; WSO2, Inc. 

[email protected]