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