All docs This doc
Skip to end of metadata
Go to start of metadata

Here are few things that might be useful to you when developing applications to be deployed in WSO2 Integration Cloud:

Applications and services

You can deploy applications and services such as WSO2 ESB, Microservices, WSO2 Data ServicesJaggery in WSO2 Integration Cloud. There are several types of applications and services that are supported by default. You can also use custom Docker images to deploy any other type of application of your choice. Each application or service type that you deploy in WSO2 Integration Cloud has a file type.

 Click to

Here are the file types of different app types and the best practices to follow when creating them:

 App Type Archive File Type
WSO2 ESB Composite applications


See Develop WSO2 ESB applications.

WSO2 Data Services


See Develop WSO2 Data Services.

Java Microservices


See Develop Java Microservices.

Jaggery applications


When creating the ZIP file, select all of the application's artifacts (Alt+A), right-click on the selected files, and then click Archive or a similar option available.

Java Web Appplication.war
PHP Application


When creating the ZIP file, select all of the application's artifacts (Alt+A), right-click on the selected files, and then click Archive or a similar option available.

Other application typesSee Develop custom Docker images.

Back to Top ^

Develop WSO2 ESB applications

You can create and manage your integration applications using WSO2 Integration Studio, which is a drag-and-drop graphical development environment.

 Click to

WSO2 Integration Studio allows you to develop services, features, and artifacts and manage their links and dependencies through the graphical editor. Here are the basic steps:

For a step-by-step tutorial on how to create an ESB composite application from scratch, see Use a WSO2 ESB Connector to Invoke Third Party Functionality.

Develop WSO2 Data Services

You can host the data services that you create using WSO2 Data Services Server (DSS) in WSO2 Integration Cloud. WSO2 Data Services Server is a platform for creating and hosting data services. 

 Click to

To create a data service,

  • See Create a Data Service.
  • Bundle the data service that you created as a composite application archive (.car file) using WSO2 Integration Studio. See Working with DSS Tooling.
  • Once you have the car file, go to WSO2 Integration Cloud, click  CREATE APPLICATION, and then create a WSO2 Data Service using the .car file.

Develop Java Microservices

WSO2 Microservices Framework for Java (MSF4J) is a lightweight, high performance framework for developing and running microservices.

 Click to

To create a microservice,

  • See on creating a WSO2 MSF4J application and obtaining the .jar file.
  • Go to WSO2 Integration Cloud, click CREATE APPLICATION, and then create a Java Microservice using the .jar file.

Develop custom Docker images

You can deploy any type of application as a custom Docker image in WSO2 Integration Cloud. You upload your Docker image to a docker registry (e.g., the Docker Hub ) and then create applications using it. At the moment, you can only use images in public registries. We will soon extend this facility to private registries as well.

 Click to

Here's how you create any type of application in the Integration Cloud:

  • Install Docker and create an account in Docker Hub.
  • Go to the folder of your sample application and execute the following command to create a Docker image in Docker Hub.

    Tip: The services running in the custom docker images in WSO2 Integration Cloud can only be exposed via ports 80 and 443. 

    The custom docker image routes traffic through one pair of ports from (9763,9443), (8080,8443), and (8280,8243). Traffic from port 80 goes through the first port in the pair while traffic from port 443 goes through the second. 

    If you want to configure a port that is not listed above, please contact us via the Support link in WSO2 Integration Cloud.
    docker build -t <your_docker_hub_user_name>/<desired_docker_image_name>:<desired_tag> .
    For example: docker build -t maheshcwso2/node-js-hello:nonroot8080 .
    docker push

    Tip: Be sure to note the following when writing the Docker file:

    • Do not use the VOLUME command in the docker file (i.e., no host mounting).
    • Do not use the root user for the container.

      RUN useradd -ms /bin/bash nonRootUser
      USER nonRootUser
    • Avoid SSH services running inside the container.
  • The Docker image is now pushed to Docker Hub. Copy its URL.

  • Go to WSO2 Integration Cloud, Click CREATE APPLICATION, and then click the Custom Docker Images menu.
  • Upload the Docker image using the Docker Hub URL that you got earlier. 
  • After you have uploaded the image, you can create any number of applications using that custom Docker image.

Back to top ^

Use environment variables

Environment variables allow you to change an application's internal configuration without changing its source code. It is recommended to use environment variables to set the values of dynamic properties rather than hard coding them in your source code. 

 Click to

You only have to redeploy the applications through the Integration Cloud's UI for the environment variables to take effect. You can use environment variables to set database connections details (e.g., database URL, username, and password), change Log4j properties, system properties etc.

Here's a list of environment variables that you can use for each application type:

  • JAVA_OPTS : Used by servers and Java apps to configure parameters.
    For example, -XX:NativeMemoryTracking=summary -Xms256m -Xmx1500m -XX:ThreadStackSize=256 -XX:MaxMetaspaceSize=256m.
  • JFR_FLAG : Used to create a Java Flight Recorder (JFR) report. JFR is disabled by default. Set this to true to enable it.
    You can later contact the WSO2 Cloud team to collect the report generated in the servers
  • JAVA_OPTS : Used by servers and Java apps to configure parameters .
    For example, -XX:NativeMemoryTracking=summary -Xms256m -Xmx1500m -XX:ThreadStackSize=256 -XX:MaxMetaspaceSize=256m.
  • TENANT_PASSWORD : Used to change the tenant admin's default password.
  •   ADMIN_PASSWORD : Used to change the Cloud's super admin's default password.
  • TIMEZONE : Used to change the time zone of the server. For example, when the time zone of the EC2 instance where your application is deployed in is not the same as the time zone of your physical location. For example, EST for Eastern standard time.
  • LOG4J_PROPERTIES : Used to pass any number of log4j properties in a comma-separated list in environment variables. For example, add an environment variable with the information below to enable wire logs:
  • SO_TIMEOUT : Used to set the maximum period of inactivity between two consecutive data packets in milliseconds. The default value is 60000 ms.
  • JFR : To create a Java Flight Recorder report. You can collect the report by contacting the WSO2 Cloud team later.

The following properties are used to configure the email server:


JAVA_OPTS : Used by servers and Java apps to configure parameters .
For example, -XX:NativeMemoryTracking=summary -Xms256m -Xmx1500m -XX:ThreadStackSize=256 -XX:MaxMetaspaceSize=256m.

WORKER_THREAD_POOL_SIZE : Used to reduce the number of application threads and provide management of the worker threads.
ENABLE_JFR : To create a Java Flight Recorder (JFR) report, set the value to true. JFR is disabled by default. You can later contact the WSO2 Cloud team to collect the report generatedin the servers.

Jaggery JAVA_OPTS : Used by servers and Java apps to configure parameters .
For example, -XX:NativeMemoryTracking=summary -Xms256m -Xmx1500m -XX:ThreadStackSize=256 -XX:MaxMetaspaceSize=256m.
DataServices JAVA_OPTS : Used by servers and Java apps to configure parameters .
For example, -XX:NativeMemoryTracking=summary -Xms256m -Xmx1500m -XX:ThreadStackSize=256 -XX:MaxMetaspaceSize=256m.

To add new environment variables or edit existing ones, click your application in the Integration Cloud to open it, and then click its Environment Variables menu.

Then, enter the environment variabe as a key-value pair as shown in the example below:

Back to Top ^

Test applications

See tutorial Test your Applications Locally before Deploying in the Cloud.

Connect to databases

To create a database in the Integration Cloud, click the settings icon in the top, right-hand corner of the Cloud's UI and click  Databases

App development best practices

  • We recommend you to develop and test your applications locally before deploying in the Cloud.
  • You deploy archive files to your tenant of the Cloud.
  • Use the Cloud's databases or a similar service to store your ESB configurations. Due to the container model of the Cloud, registry configurations can be reset when the ESB instance restarts.
  • Cloud's file system is read-only. To edit them, contact WSO2 using the Support link in the Cloud UI.
  • Use environment variables to set dynamic properties. For a list of environment variables, see Use environment variables
  • Use the twelve-factor app building methodology.
  • Note that clustering support is not available, but your application should be able to scale horizontally
  • Applications should be able to work in a stateless manner.

  • To add more ESB users, contact the WSO2 Cloud team. Only the Admin user is supported for the ESB by default.

Configure outgoing mail servers

WSO2 Integration Cloud does not allow to relay emails to standard SMTP ports including 25, 465, and 587. It is recommended to use authenticated SMTP servers on higher ports for relaying emails.

Manage memory

It is recommended to run tools like NMT to understand how the JVM allocates memory to Java applications and allocate JVM Heap and related parameters accordingly.

Be sure to the JAVA_OPTS as follows to all Java applications to ensure that there won't be any memory issues:

JAVA_OPTS: -Xms256m -Xmx1500m -XX:MetaspaceSize=256m

  • No labels