[Article] WSO2 Developer Studio - Development and Deployment Best Practices

Table of contents

• Applies to
• Introduction
• Development best practices
  • Project Creation
  • Creating ESB Projects
  • Creating Multiple Projects
  • Source Control
• Deployment Best Practises
  • Deploying to Multiple Environments
  • Remote Deployment
    • Remote deploy with Maven car deploy plugin

Applies to

Introduction

WSO2 Developer Studio (WSO2 DevStudio) is the development tool (IDE) recommended by WSO2 to develop applications for the WSO2 platform, such as ESB configurations and BPS and DSS projects. WSO2 DevStudio also supports a wide range of web application development including JAX-RS, JAX-WS, Axis2 Services and Web apps. This comes in the form of an Eclipse plugin as well as a pre installed (to Eclipse) binary.

WSO2 DevStudio simplifies the creation of artifacts (with the use of graphical editors) and the management of dependencies between these artifacts. DevStudio not only supports the usual development-testing-debugging process but also supports the deployment of artifacts into your servers. Servers can be on-premise or on the Cloud, as WSO2 DevStudio provides a unique and simplified deployment model. DevStudio supports the following WSO2 servers for creating projects and artifacts:

• WSO2 Enterprise Service Bus
• WSO2 Data Services Server
• WSO2 Application Server
• WSO2 Business Process Server
• WSO2 Business Rules Server
• WSO2 Governance Registry

There are several other project types (supported projects) that are available. The full list can be found in the IDE dashboard and in this documentation.

Development best practices

Project creation

With WSO2 DevStudio you can create projects from the beginning or they can import previously created projects or artifacts into existing projects. A guide on how to create different types of projects can be found in this documentation.
Following are some important points to consider when creating projects:

• The WSO2 DevStudio IDE starts with a default workspace. We recommend you to change this default location to a location of their preference that is easily accessible.
• When creating a new project, it also comes with a default location, however similar to the workspace, you can select a location of their preference. It is recommended to create a Maven Multi Module (MMM) project to group the projects for a given use case. As soon as the project structure is created it is recommended to add them to source control (e.g. SVN and Git).
• Note that all the project listed here are Maven projects, so follow proper Maven naming convention when creating projects.
• Make sure you properly define the groupid, artifactid and version. A good example is shown below:
  

      org.wso2.integration.sample
      esb-demo-project
      1.0.0
    

Creating ESB projects

An ESB project would contain artifacts such as proxy services, APIs, endpoints, sequence tasks, message stores, message processors, local-entries and templates¹. Following are some important points to consider when creating ESB artifacts:

• For each artifact use a proper naming convention from the beginning.
• If an ESB project contains many artifacts related to different use cases, name the artifacts by prefixing or postfixing the use case name. However the better approach would be to have different ESB projects for different use cases.
• When we have a common set of code, a best practice is to implement them in a sequence or a template that is reusable.
• When creating endpoints try to use defined endpoints and the key of the defined endpoint in the configuration (instead of defining the endpoint inline in the configuration). This would give you better flexibility when endpoints need to be changed or moved².

Creating multiple projects

Most of the time you may need to create multiple projects. For example, you need to create backend service (application server), ESB, front-end (Web app) and other supportive projects. In this kind of situation we recommend you to create them under a Maven Multi Module (MMM) project.

When we have multiple projects under a common goal (eg for a particular use case) create a MMM project first, and then create the other projects inside it. An example structure is shown below:

Integration_Parent_Project
   |___ AppServerProject
   |___ ESBConfigProject
   |___ RegistryProject
   |___ CappProject

MMM is a wrapper Maven project that has child projects as Maven modules. For example, see the following MMM project’s POM file:

    org.wso2.integration.sample
    Integration_ParentProject
    1.0.0
    pom
    Integration_ParentProject
    
      CappProject
      ESBConfigProject
      RegistryProject
      AppServerProject
    
     …
  

The advantage of creating an MMM project is that you can build all the child projects in a single command. Also, if you need to perform any automation tasks such as executing other Maven plugins before or after a build, you can easily perform it here.

Source control

It is always recommended to use source control for projects when tracking as a fail safe mechanism.

Following are some important points:

• You can ignore the .settings directory and target the directory that’s being source controlled. Add these to ignore list in the respective source control (Git or SVN) system
• Do not ignore the artifacts.xml file and .project file as these contain the data required to display the project
• For ESB projects you can ignore the ‘graphical-synapse-config’ directory as this is auto generated (note that WSO2 DevStudio 3.8.0, onwards graphical files will not being used)

Deployment best practices

WSO2 DevStudio allows you to package your artifacts into a Composite Application aRchive (CAR) and deploy it to WSO2 servers such as WSO2 Application Server and WSO2 Enterprise Service Bus among others. Servers may be running on the Cloud or on-premise. WSO2 DevStudio handles both in the same way.

Figure 1

The three main ways to deploy artifacts to WSO2 servers are by

1. Using the export as a .car file option³ or using Maven build to create the CAR file and deploying it in the server.
2. Deploying from the WSO2 DevStudio servers view⁴.
3. Deploying from the Maven plugin⁵.

All of the above approaches need to have a composite application project⁶ to create a .car file.

Following are some important points:

• Deploying from Maven plugin(3) or from a CAR file(1) would be the better approach for deploying in production environments. Deploying via Maven plugin gives you the ability to deploy the CAR file into multiple servers. All you need to do is configure the server urls and credentials in the maven plugin.
• The C-App can be deployed to any Carbon server and only the relevant artifacts will be deployed to specific servers depending on the server roles.

Deploying to multiple environments

Following are some important points:

• When it comes to multiple environments like DEV, QA, PROD, you need to have different C-App projects to group the dynamic artifacts for different environments such as endpoints, WSDLs and policies. You also have to have another C-App project to hold common (environment independant) artifacts where you can deploy the same in all environments.
• Try to place artifacts as registry resources for different environments, so that it’s easy to manage environments. Refer to this article for more information.
• For example, if we consider two environments - DEV and QA - the ‘Integration_Parent_Project’ discussed above would look as follows:
  

  Integration_Parent_Project
     |___ AppServerProject
     |___ ESBConfigProject
     |___ RegistryProject 
     	|___ DEV
  	|___ QA
     |___ CappProject_Common
     |___ CappProject_DEV
     |___ CappProject_QA
  

Here RegistryProject contains two folders to keep the resources required for the DEV and QA environments. For example, let's say you have two different backend endpoints for development (DEV) and quality assurance (QA). You can create these endpoints in DEV and QA folders respectively. This approach allows you to create endpoints with same resource name and different artifact names (you have to maintain different artifact names because having two artifacts with the same artifact name is not allowed). Refer to the image attached in the appendix at the end of this article.

	|___ RegistryProject  
		|___DEV
			|__ backendEP.xml     //points to dev backend, https://dev.wso2as.com/9763
		|___QA
			|__ backendEP.xml     //points to qa backend,  https://qa.wso2as.com/9763

The purpose of CappProject_Common is to keep the environment independent resources in a way that the CAR file generated from this can be deployed in all environments. The CappProject_DEV would be used to package the DEV resources and CappProject_QA is used to package the QA resources. This makes it easy to move from DEV to QA - all you need to do is deploy the correct .car file.

Remote deployment

As discussed in the beginning, when you have multiple projects it is a best practise to implement them within a parent project. Once the parent project is built from Maven, you will get the .car file created in the target directory of the C-App Project. You can simply deploy the CAR file to the servers using its management console.

However, when it comes to automation and testing, to make this manual process easier, WSO2 tooling provides a solution called “Maven CAR deploy plugin”.

Remote deploy with Maven CAR deploy plugin

The CAR deploy plugin needs to be configured with the server URL, username and password of the server admin. Additionally you have to have server’s public certificate in your truststore (which is accessible by the plugin) and truststore password. This plugin needs to be configured inside the plugins section of the composite application project’s POM file. A sample configuration would look as follows:

   org.wso2.maven
   maven-car-deploy-plugin
   1.0.9
   true
   
    
     
/home/wso2esb-4.7.0/repository/resources/security/wso2carbon.jks
      wso2carbon
      JKS
      https://localhost:9443
      admin
      admin
      deploy
     
    
   

In the above configuration, note the CarbonServer tag. Here you can deploy to many servers. All you need to do is define the server configurations. Once the plugin is configured, you can perform the remote deployment using the following command.

  mvn clean deploy -Dmaven.deploy.skip=true -Dmaven.car.deploy.skip=false

This makes sure that only the .car file is deployed to the defined carbon servers.

If you want to shorten the command, you can also configure the above options within the .pom file. For that add following lines into the properties section of the C-App project's pom.xml file.

false false 

A sample configuration is shown below:

   com.example.Capp
  Capp
  1.0.0
  carbon/application
  Capp
  
    false
    true
    …. 
  
  …

Once the above configuration is completed, the deploy command will be shortened to:

mvn clean deploy

A security concern of this plugin is the use of plain text passwords. Currently there is no option to use encrypted passwords in the plugin configuration. However you can configure the plugin to provide the password in the command rather than having it in the configuration. For that we have to use variables for the username and password in the plugin configuration. Replace the username and password fields as follows:

      ...
      https://localhost:9443
      ${username}
      ${password}
      ...

Then in the command line give the username and password as arguments as shown below:

        mvn clean deploy -Dusername=admin -Dpassword=admin

Conclusion

In this article we discussed best practices that you can follow with WSO2 DevStudio while developing SOA projects. We discussed frequently used activities such as creating single or multiple projects, using maven with WSO2 DevStudio, deploying to multiple environments and remote deployment with WSO2 DevStudio.

References

• [1] https://docs.wso2.com/display/DVS371/Creating+ESB+Artifacts
• [2] https://docs.wso2.com/display/ESB481/Indirect+and+Resolving+Endpoints
• [3] https://docs.wso2.com/display/DVS371/Packaging+Artifacts+Into+Deployable+Archives#PackagingArtifactsIntoDeployableArchives-CreatingaCompositeApplicationArchive(CAR)file
• [4] https://docs.wso2.com/display/DVS371/Deploying+and+Debugging#DeployingandDebugging-DeployingaC-ApptoarunningserverinsideEclipse
• [5] https://docs.wso2.com/display/DVS371/Deploying+and+Debugging#DeployingandDebugging-DeployingaC-ApptomultipleserversusingtheMavenplug-in
• [6] https://docs.wso2.com/display/DVS371/Packaging+Artifacts+Into+Deployable+Archives

Appendix

Figure: Resource Name and Artifact Name