Running WSO2 dataservices-2.5.1 on IBM WebSphere 6.1

Applies To 

Table of Contents

1. Preparing WebSphere

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

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

startServer.bat server1 

2. Building a deployable artifact

Next, build a deployable artifact from the WSO2 Data Services Server binary distribution so that it can be deployed on WebSphere server. Download WSO2 Data Services Server-2.5.1 from wso2.org/downloads/dss. Extract the downloaded .zip into a directory. Copy repository and resources directories into a new folder. Hereafter, refer to this new directory as ds-repo, i.e. C:\dss\ds-repo.

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

- repository

- resources

- ds.war

The contents of the ds.war will be;

ds.war

 - WEB-INF

   - plugins

   - patches

   - lib

   - eclipse

   - classes

   - web.xml

Point to the created ds.war during the installation process. In order to enable WSO2 Carbon logging inside WebLogic, copy log4j.properties file in the extracted WSO2 Data Services-2.5.1 directory to ds.war\WEB-INF\classes. 

3. Configuring SSL on WebSphere

Enable SSL in the WebSphere server since the interactions with the WSO2 Data Services Server will happen through HTTPS. Login to the 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:\dss\ds-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 in the SSL certificates and keystore management page. Click on NodeDefaultSSLSettings. Select wso2carbon_ks as TrustStore 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 DSS on WebSphere. 

4. Updating the WSO2 Data Services Server configuration files

The WSO2 Data Services Server is provided with a set of configuration files in DS_HOME (root of the binary distribution) /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 ds-repo\repository\conf directory.

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

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

Please note, WebSphere has now been configured to run on 9444 HTTPS port.
To deploy WSO2 DSS on WebSphere server on non-root webContext, update the WebContextRoot element as follows:

<WebContextRoot>/ds</WebContextRoot>

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

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

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

<url>jdbc:h2:C:\dss\ds-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:

<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. Installing the WSO2 Data Services Server on WebSphere

The required configurations have been completed and, now, we are ready to deploy the WSO2 DSS 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\dsprofile\bin.

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

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

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

Run startServer.cmd server1.

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

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

Browse the file path of ds.war which has been created in step 2. Make sure to specify /ds as the Context root. Click on Next to proceed through the wizard. Proceed with accepting the default values for 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. ds_war will be shown under the Enterprise Applications list as follows:

Select ds_war and click on Start to start the WSO2 DSS on WebSphere. If it is successful, the application status will be marked in green.

Now, the WSO2 Data Services management console can be accessible using https:\\localhost:9444\ds\carbon.

Author

Charitha Kankanamge

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

[email protected]