In this post I'll explain how to deploy Carbon 4.0.2 as a web-application in Apache Geronimo V3. I'm using the Geronimo J2EE distribution with Tomcat 7 integration for Linux platform downloaded from here.
Please Note:
The Steps
The basic steps are similar to what is explained by Pradeep in his blog on running Carbon 4.0 as a web-app in Apache Tomcat. So I would suggest reading his blog to understand the basics on running Carbon based products in web-app-mode on any other Web Server.
Here I will explain the steps to deploy Carbon web-app in Geronimo and explain what are the tweaks and changes we need to do in Geronimo to run Carbon web-app.
1. Download Carbon 4.0.2 from the previous releases page here
2. Extract carbon-4.0.2 in the file-system.
The extracted directory will be considered $CARBON_HOME from here onwards.
3. The web-app directory for Carbon is in $CARBON_HOME/webapp-mode directory. Inside it you will find the WEB-INF folder which contains the web-application descriptors and required libraries to run Carbon web-application. The structure of the WEB-INF directory is as below;
WEB-INF/
├── eclipse
│ └── launch.ini
├── lib
│ └── org.wso2.carbon.bridge-4.0.0.jar
└── web.xml
The web.xml is the web-application descriptor that includes details about the Carbon web-app. Please note that the web-app ID will be taken as the web-context root if you don't include a geronimo-web.xml descriptor specifying the Web-Context information, under your web-application. So in this case the Carbon web-app ID is : WebApp
4. Create a .war archive file with above content in WEB-INF directory so that we can deploy it in Geronimo. I'm creating the archive as carbon.war.
eg: jar -cvf carbon.war WEB-INF/
5. Now we need to configure the carbon-repository to be used by our carbon web-application. For this create a directory named carbon_repo and copy the repository sub-directory under $CARBON_HOME, to carbon_repo directory.
We'll call this directory $CARBON_REPO from here onwards.
For me this location is at: /home/dileepa/work/carbon_repo
Also change the JMX ports in carbon.xml to some other accepted port number to avoid address conflicts with host Geronimo's RMI ports.
To support embedded derby database connection, you need to add the derby embedded driver bundle to $CARBON_REPO/repository/components/plugins and add below entry to bundles.info.
derby,1.0.0,plugins/derby_1.0.0.jar,4,true
You can download the derby_1.0.0 bundle from the hosted location here.
To enable Carbon Logging, you need to make the log4j.property file available for carbon logging bundle in $CARBON_REPO/repository/components/plugins. In standalone Carbon 4 based products, this is achieved by bundling the log4j property file as a fragment bundle and deploying it on the fly as from dropins. But as we are deploying the carbon runtime in bridge mode we cannot install dropins, so we have to manually copy it to $CARBON_REPO/repository/components/plugins directory and add the relevant entry in the bundles.info as below;
org.wso2.carbon.logging.propfile,1.0.0,plugins/org.wso2.carbon.logging.propfile_1.0.0.jar,4,true
You can download the org.wso2.carbon.logging.propfile_1.0.0.jar bundle from the hosted location here.
9. Now configure $CARBON_REPO/repository/conf/user-mgt.xml and registry.xml using the above created datasource JNDI name.
10. Now the $CARBON_REPO is configured.
You now need to set the carbon.home system property required to run Carbon.
Set the carbon.home system property in $GERONIMO_HOME/etc/system.properties as below;
carbon.home=/home/dileepa/work/carbon_repo
10. Now the environment is set for deploying carbon web-app in Geronimo. So start Geronimo server by executing below command;
$GERONIMO_HOME/bin$ ./geronimo run
To deploy the carbon.war we created in step 4, deploy the carbon.war in Geronimo server by going to the Deployer section in console and giving the carbon.war archive to install.
Now when deploying carbon.war if you see below error it's due to a aries-jndi bug in 0.3.0 version discussed in ARIES-554.
To fix the JNDI issue you need to update the aries-jndi bundle and it's dependencies.
For that please follow below steps;
Please Note:
WSO2
Carbon platform is a fully fledged cloud-native middleware platform
with it's own set of complexities which are greater than a typical
web-application or other deployable artifact.
Running
WSO2 products in web-app mode or any other deployable form in 3rd party
AppServers can greatly limit the capabilities of the the platform and
can introduce new complexities when combined with the host AppServer's
environment and complexities.
Therefore running WSO2 Products in other AppServers is not encouraged and subject to specific support conditions only.
Therefore running WSO2 Products in other AppServers is not encouraged and subject to specific support conditions only.
The Steps
Here I will explain the steps to deploy Carbon web-app in Geronimo and explain what are the tweaks and changes we need to do in Geronimo to run Carbon web-app.
1. Download Carbon 4.0.2 from the previous releases page here
2. Extract carbon-4.0.2 in the file-system.
The extracted directory will be considered $CARBON_HOME from here onwards.
3. The web-app directory for Carbon is in $CARBON_HOME/webapp-mode directory. Inside it you will find the WEB-INF folder which contains the web-application descriptors and required libraries to run Carbon web-application. The structure of the WEB-INF directory is as below;
WEB-INF/
├── eclipse
│ └── launch.ini
├── lib
│ └── org.wso2.carbon.bridge-4.0.0.jar
└── web.xml
4. Create a .war archive file with above content in WEB-INF directory so that we can deploy it in Geronimo. I'm creating the archive as carbon.war.
eg: jar -cvf carbon.war WEB-INF/
5. Now we need to configure the carbon-repository to be used by our carbon web-application. For this create a directory named carbon_repo and copy the repository sub-directory under $CARBON_HOME, to carbon_repo directory.
We'll call this directory $CARBON_REPO from here onwards.
For me this location is at: /home/dileepa/work/carbon_repo
carbon_repo/
└── repository
├── components
├── conf
├── data
├── database
├── deployment
├── logs
├── README.txt
├── resources
└── tenants
Now;- Remove all the tomcat related jars from the '$CARBON_REPO/repository/components/plugins' directory. As Geronimo provides Tomcat servlet container by default we don't need these bundles in runtime.
org.wso2.carbon.tomcat_4.0.1.jar
org.wso2.carbon.tomcat.ext_4.0.2.jar
org.wso2.carbon.tomcat.fragment.dummy_4.0.0.jar
org.wso2.carbon.tomcat.patch_4.0.1.jar
tomcat-ha_7.0.28.wso2v1.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.0.0.jar and org.wso2.carbon.servletbridge-4.0.0.jar
- Now we need to configure the bundles.info to add these 2 new bundles in the runtime. Add the below 2 lines to $CARBON_REPO/repository/components/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info
org.wso2.carbon.http.bridge,4.0.0,plugins/org.wso2.carbon.http.bridge-4.0.0.jar,4,true
org.wso2.carbon.servletbridge,4.0.0,plugins/org.wso2.carbon.servletbridge-4.0.0.jar,4,true
6. We now need to setup the HTTPS connector configuration for tomcat in Geronimo to handle connections to carbon web-app.
To do this; add a HTTPS Connector configuration to $GERONIMO_HOME/var/catalina/server.xml
I'm configuring a new HTTPS connector for port : 8445 in Geronimo's tomcat server using the default carbon-keystore as below;
eg:
Then configure Axis2 transports in $CARBON_REPO/repository/conf/axis2.xml
Now configure the serverURL and the web-context root (the web-context root for our scenario is /WebApp) in carbon.xml
8080 8445
/WebApp https://localhost:8445/WebApp/services/
Also change the JMX ports in carbon.xml to some other accepted port number to avoid address conflicts with host Geronimo's RMI ports.
9998 11112
7. Endorsing JVM provided classes
Copy the endorsed lib jars found under $CARBON_HOME/lib/endorsed to $GERONIMO_HOME/lib/endorsed to provide the endorsed libraries required for XML parsing/API etc.
Copy the endorsed lib jars found under $CARBON_HOME/lib/endorsed to $GERONIMO_HOME/lib/endorsed to provide the endorsed libraries required for XML parsing/API etc.
8. Configuring the Carbon Datasource in Geronimo.
We need to configure a Carbon datasource in Geronimo for the Registry and User Manager in Carbon. For this purpose please follow the blog-post on how to create an embedded-derby Carbon datasource in Geronimo. Similarly you can create the datasource using any database type and configure the master-datasources.xml to use it.
Now use the JNDI name and the URL of the created datasource with the relevant database driver in $CARBON_REPO/repository/conf/datasources/master-datasources.xml
eg:
WSO2_CARBON_DB The datasource used for registry and user manager jca:/console.dbpool/WSO2CarbonDB/JCAConnectionManager/WSO2CarbonDB jdbc:derby:/home/dileepa/work/geronimo-tomcat7-javaee6-web-3.0.0/var/derby/WSO2_CARBON_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000 wso2carbon wso2carbon org.apache.derby.jdbc.EmbeddedDriver 50 60000 true SELECT 1 30000
To support embedded derby database connection, you need to add the derby embedded driver bundle to $CARBON_REPO/repository/components/plugins and add below entry to bundles.info.
derby,1.0.0,plugins/derby_1.0.0.jar,4,true
You can download the derby_1.0.0 bundle from the hosted location here.
To enable Carbon Logging, you need to make the log4j.property file available for carbon logging bundle in $CARBON_REPO/repository/components/plugins. In standalone Carbon 4 based products, this is achieved by bundling the log4j property file as a fragment bundle and deploying it on the fly as from dropins. But as we are deploying the carbon runtime in bridge mode we cannot install dropins, so we have to manually copy it to $CARBON_REPO/repository/components/plugins directory and add the relevant entry in the bundles.info as below;
org.wso2.carbon.logging.propfile,1.0.0,plugins/org.wso2.carbon.logging.propfile_1.0.0.jar,4,true
You can download the org.wso2.carbon.logging.propfile_1.0.0.jar bundle from the hosted location here.
9. Now configure $CARBON_REPO/repository/conf/user-mgt.xml and registry.xml using the above created datasource JNDI name.
- In user-mgt.xml change the datasource property as below;
- In registry.xml change the dataSource as below;
10. Now the $CARBON_REPO is configured.
You now need to set the carbon.home system property required to run Carbon.
Set the carbon.home system property in $GERONIMO_HOME/etc/system.properties as below;
carbon.home=/home/dileepa/work/carbon_repo
10. Now the environment is set for deploying carbon web-app in Geronimo. So start Geronimo server by executing below command;
$GERONIMO_HOME/bin$ ./geronimo run
To deploy the carbon.war we created in step 4, deploy the carbon.war in Geronimo server by going to the Deployer section in console and giving the carbon.war archive to install.
Now when deploying carbon.war if you see below error it's due to a aries-jndi bug in 0.3.0 version discussed in ARIES-554.
ERROR [DataSourceRepository] Error in registering data source: WSO2_CARBON_DB - Error in creating JNDI subcontext 'javax.naming.InitialContext@2702c693/jca:: Unable to determine caller's BundleContext org.wso2.carbon.ndatasource.common.DataSourceException: Error in creating JNDI subcontext 'javax.naming.InitialContext@2702c693/jca:: Unable to determine caller's BundleContext at org.wso2.carbon.ndatasource.core.DataSourceRepository.checkAndCreateJNDISubContexts(DataSourceRepository.java:232) at org.wso2.carbon.ndatasource.core.DataSourceRepository.registerJNDI(DataSourceRepository.java:257) at org.wso2.carbon.ndatasource.core.DataSourceRepository.registerDataSource(DataSourceRepository.java:360) at org.wso2.carbon.ndatasource.core.DataSourceRepository.addDataSource(DataSourceRepository.java:474) at org.wso2.carbon.ndatasource.core.DataSourceManager.initSystemDataSource(DataSourceManager.java:182) at org.wso2.carbon.ndatasource.core.DataSourceManager.initSystemDataSources(DataSourceManager.java:154) at org.wso2.carbon.ndatasource.core.internal.DataSourceServiceComponent.initSystemDataSources(DataSourceServiceComponent.java:166) at org.wso2.carbon.ndatasource.core.internal.DataSourceServiceComponent.setSecretCallbackHandlerService(DataSourceServiceComponent.java:152) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)Geronimo V3 comes with aries-jndi-0.3.0 installed.
To fix the JNDI issue you need to update the aries-jndi bundle and it's dependencies.
For that please follow below steps;
- Go to OSGI bundles section in console and search for aries.jndi bundle;
- Now you need to uninstall this bundle and install the latest available org.apache.aries.jndi.1.0.0 and it's required dependencies: org.apache.aries.util.1.0.0 and org.apache.aries.proxy.1.0.0.
- You can download these aries bundles from the official Aries download site.After installing the 3 new aries bundles and starting them you can rectify the JNDI error you got before.
11. Now you can re-start the Geronimo server and access the Carbon management console at : https://localhost:8445/WebApp/carbon/
You can telnet to the osgi-console of Carbon server as below;
telnet localhost 19444
You can telnet to the osgi-console of Carbon server as below;
telnet localhost 19444
