A Carbon Application (cApp) is a collection of deployable artifacts, which can be deployed on a Carbon instance to easily port your Web services based solution from one environment to another.
When developing solutions using WSO2 Carbon platform, there can be many artifact types used in it. For example Axis2 services, Synapse artifacts (endpoints, proxy services, mediators etc.), Registry Resources, Data services etc. Normally these artifacts are developed in a development environment and then moved one by one into the staging and production environments. On each and every setup, you have to manually configure these artifacts in order to build up the entire solutions. If your solution contains many artifacts, this process can take lot of time and effort.
So the cApp concept tries to solve this problem by providing the facility to export your entire solution as a single cApp artifact and simply deploy it. WSO2 Web services development tooling environment (Carbon Studio) can be used to develop your individual artifacts and export it as a single cApp artifact. Then you can deploy it on any Carbon server which has cApp deployment capabilities.
In cApp development time, you have to specify a server role for each and every artifact in the cApp. That is because, at development time we don't know the physical server in which a particular artifact will be deployed. Therefore, a logical server role is assigned for each and every artifact.
Ex : If you are developing an Axis2 service and if you are going to deploy all your services in a single AppServer instance in the production setup, you may set the server role as "appserver1".
At the deployment time of the cApp, you have to set the server roles for each and every Carbon instance in your setup. You can set one or more roles which can be acted by the current Carbon instance. Product name is set as the default value for the server role of each product. Following three methods can be used to set the server role.
This is the easiest way to set the server role of your Carbon instance. Go to Configure > Server Roles UI and you can simply add/remove server roles. Read the "Help" page for more details on that. This is the most recommended way to configure your server roles.
In the carbon.xml file, you can find the following element.
<ServerRoles>
<Role>ApplicationServer</Role>
</ServerRoles>
You can set multiple Role elements here to specify the roles acted by the current server.
Ex : If you want this server to act as appserver1 and dataservices1 servers, configuration will be as follows. Before setting this, you have to make sure that the current server has the capabilities of deploying Axis2 services and data services.
<ServerRoles>
<Role>appserver1</Role>
<Role>dataservices1</Role>
</ServerRoles>
So when you deploy a cApp artifact on this server, all artifacts which has the above two server roles will be deployed on the current instance. Others will be ignored.
You can use the system property "serverRoles" to specify the server roles that can be acted by the current Carbon instance. So when you start the server, pass the server roles as a comma separated list as follows.
Ex : sh wso2server.sh -DserverRoles=appserver1,dataservices1
Note : Once you use the Server Roles UI to configure your server roles you can't change that configuration using other two methods. That is because when you use the UI, server roles will be stored in the Registry and after that, values in Registry are given priority over the values set using other two methods.
You can upload a cApp (.car file) into a running Carbon instance using the management console. Go to Manage > Applications > Add and you will be directed to the following page.
Here you can select your .car file by browsing the file system. After you upload the .car file, you can see a log on your console about the status of your application. If the cApp deployment is successful, go to Manage > Applications > List. You will be able to see the deployed cApp on this page as follows.
If you click on your cApp name, you will be directed to the Application Dashboard page which contains all the information about the content of the deployed cApp. It separately lists each and every artifact and you can navigate to those artifacts' information pages by clicking on those links. Application dashboard page is shown in the following image.
Note : As an alternate to uploading the cApp using the management console, you can copy your .car archive into CARBON_HOME/repository/deployment/server/carbonapps folder manually and it will be hot deployed.
It is not recommended to delete individual artifacts of a cApp. The entire cApp should be deleted. Go to Manage > Applications > List and click on Delete icon in front of the cApp to be deleted.
Note : As an alternate to deleting the cApp using the management console, you can delete your .car archive from CARBON_HOME/repository/deployment/server/carbonapps folder manually and it will be undeployed.