Running WSO2 Carbon as a web-app - Apache Tomcat

As I have explained in one of my previous posts, WSO2 Carbon has undergone some major architectural changes from its 3.x.x version to version 4. One of our main goals during those changes was to make Carbon running in a pure-OSGi container instead of running it in a bridged mode. At some point we were considering to drop off the web-app mode deployment, altogether from the C4 release on-wards.  However, thanks to sound architectural decisions that we have made in the past, we realized that it is possible to support web-app mode deployment of WSO2 Carbon without major hassles.

Why Web-app mode deployment?

More often than not, large organizations have their middle-ware platform/part of it,  in place. Not only they have application-servers/ESBs/etc ,but also they may already have built monitoring mechanisms/billing systems based on the existing echo system (Normally internal policies/politics within the organization plays a major role too ;) ). If somebody wants to make use of a WSO2 product within such restrictive environments, the web-app mode deployment of WSO2 Carbon comes to the rescue.

Having said that we strongly recommend running WSO2 Carbon servers in standalone mode.

Pre-requisites

Download Apache Tomcat 7.0
Download WSO2 Carbon 4.x.x

Steps to deploy

Creating the war file
 Extract the product zip directory to the local file-system. From here onwards I'm referring the root of the extracted product directory as $CARBON_HOME.

Under the directory $CARBON_HOME/webapp-mode there is a directory called WEB-INF. As the name suggests, this is the Carbon bare bones web-app. Move it in to a directory with a preferred name. and put the whole directory structure in to the 'webapps' directory of Apache-Tomcat. My preferred directory name is 'crbn'  - please note that, the name of this directory will get picked as the context root of our web-app by Tomcat.

Now the  directory structure is similar to,


crbn/
└── WEB-INF
    ├── eclipse
    │   └── launch.ini
    ├── lib
    │   └── org.wso2.carbon.bridge-4.0.0.jar
    └── web.xml


Configuring the Carbon repository

• Create a directory named "carbon_repo" in a preferred location. For me its located in '/home/pradeep/carbon_repo'. Copy the 'repository' directory found under $CARBON_HOME to the newly created 'carbon_repo' directory.

       From here on-wards of this blog post, I'm referring the directory location of   'carbon_repo' as $CARBON_REPO

        Now the directory structure would look like,

         

        carbon_repo/

                          └── repository

                                        ├── components

                                        ├── conf

                                        ├── data

                                        ├── database

                                        ├── deployment

                                        ├── logs

                                        ├── README.txt

                                        ├── resources

                                        └── tenants

• Replace the DB file location found in '$CARBON_REPO/repository/conf/datasources/master-datasources.xml' with the new path.

         The new master-datasource.xml DB location entry looks like,

• Remove all the tomcat related jars from the '$CARBON_REPO/repository/components/plugins' directory.  The jars represent the embedded version of tomcat. Since our intention is to run carbon under provided servlet container, we no longer need theses jars. The list of jars include,

           org.wso2.carbon.tomcat_4.x.x.jar 

           org.wso2.carbon.tomcat.ext_4.x.x.jar

           org.wso2.carbon.tomcat.fragment.dummy_4.x.x.jar

           org.wso2.carbon.tomcat.patch_4.x.x.jar 

           tomcat_7.0.28.wso2v1.jar

• copy the jars found under $CARBON_HOME/webapp-mode/bundles to '$CARBON_REPO/repository/components/plugins'  directory. namely,

          org.wso2.carbon.http.bridge-4.x.x.jar 

          org.wso2.carbon.servletbridge-4.x.x.jar

       

          and add the following two entries to the 'bundles.info' located under    '$CARBON_REPO/repository/components/configuration/org.eclipse.equinox.simpleconfigurator' directory.

org.wso2.carbon.http.bridge,4.x.x,plugins/org.wso2.carbon.http.bridge-4.x.x.jar,4,true

org.wso2.carbon.servletbridge,4.x.x,plugins/org.wso2.carbon.servletbridge-4.x.x.jar,4,true

Configure Tomcat connectors
To enable https connector in Apache-tomcat edit, $CATALINA_HOME/conf/server.xml


Configure Axis2 transports

Configure '$CARBON_REPO/repository/conf/axis2.xml with the updated transport pors.

Configure webContextRoot and backendServerURL in carbon.xml

Update the fields to,

respectively in the '$CARBON_REPO/repository/conf/carbon.xml'

Endorsing JVM provided classes

Like any other complex java program, Carbon makes use of endorsed libraries for XML parsing/APIs/etc. To endorse libs,
create a directory named 'endorsed' in $TOMCAT_HOME .  Move all the jar files found under  $CARBON_HOME/lib/endorsed to newly created $TOMCAT_HOME/endorsed directory.

Starting the server and accessing the management console

set the CARBON_HOME system property to the created 'carbon_repo' directory,

export CARBON_HOME=/home/pradeep/carbon_repo

start Tomcat server, using,

./bin/catalina.sh run

access the carbon management console using,

https://10.100.2.1:8443/crbn/carbon


Please Note

WSO2 Carbon is a fully fledged server runtime. This blog post is for get it working with Apache Tomcat servlet container. The steps depend on the application server.