Running WSO2 Carbon-3.X based products on JBoss 5.X

We will refer to the below WSO2 Carbon-3.X 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. We will also refer to the JBoss installation directory as JBOSS_HOME.

Applies To 

Table of Contents

4.1
4.2 WSO2 Identity Server configurations

1. Building a deployable artifact

First, we need to build a deployable artifact with the WSO2 product binary distribution so that it can be deployed on JBoss server. Download any of the above WSO2 Carbon-3.X based product from wso2.org/downloads. Extract the downloaded .zip into a directory (WSO2_PRODUCT_HOME). Copy the 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 new directory, wso2.war, by including the WEB-INF directory located at the webapps\ROOT directory of WSO2_PRODUCT_HOME. Note that, If you are using WSO2 Carbon 3.1.0 based product (eg:- WSO2 Governance Registry 3.6.0, WSO2 Application Server 4.0.0) WEB-INF directory is located at lib\core 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;

In order to enable WSO2 Carbon logging inside JBoss, copy log4j.properties file in WSO2_PRODUCT_HOME\lib directory to wso2.war\WEB-INF\classes. 

2. Configuring SSL on JBoss

Now, we should enable SSL in JBoss server since the interactions with the WSO2 server will happen through HTTPS. In order to do that, edit the following element in JBOSS_HOME\server\default\deploy\jbossweb.sar\server.xml. Make sure to specify the absolute path of wso2carbon.jks as shown below. 

<!-- SSL/TLS Connector configuration using the admin devl guide keystore-->
<Connector protocol="HTTP/1.1" SSLEnabled="true"
port="8443" address="${jboss.bind.address}"
scheme="https" secure="true" clientAuth="false"
keystoreFile="C:\wso2\wso2-repo\resources\security\wso2carbon.jks"
keystorePass="wso2carbon" sslProtocol = "TLS" /> 

3. Updating WSO2 Product configuration files

WSO2 Carbon based products are provided with a set of configuration files in the 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 in the wso2-repo\repository\conf directory.

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

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

Note that JBoss has been configured to run on 8443 HTTPS port.
To deploy the WSO2 product on JBoss 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 to the WSO2 ESB.

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

4. 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 5.

4.1 WSO2 ESB configurations

To install the WSO2 ESB on JBoss, 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.

4.2 WSO2 Identity Server configurations

If you install the WSO2 Identity Server on JBoss, 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 JBoss.

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

5. Installing the WSO2 Product on JBoss

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

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

Copy the deployable artificat which has been created at step 1 (wso2.war directory) to JBOSS_HOME\server\default\deploy directory.

Open a new command window (or shell) and change the directory to JBOSS_HOME\bin (eg:- cd C:\\jboss-5.1.0.GA\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.

Start the server by executing run.bat or run.sh with -b option as follows. -b option is used to bind jboss server to a fixed IP.

run.sh -b <server_ip>

Once the server has started successfully, the WSO2 Carbon management console will be accessible using https://<server_ip>:8443/wso2/carbon.

Author

Charitha Kankanamge

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

[email protected]