Getting Started with WSO2 Cloud Virtual Machines for Amazon EC2

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Chintana Wilamuna
  • 17 Nov, 2009


To cater to ever more demanding business software applications, enterprises must take advantage of cutting edge, powerful hardware. The cost and burden of procuring, monitoring and maintaining these servers are increasing as the need for resource consumptions goes up. Also, any business critical application or an application that attracts large amount of traffic should be able to operate under those heavy loads. By purchasing the most powerful computer hardware will enable the enterprises to be able to operate smoothly under heavy loads. Realistically, most applications tend to have a low number of users initially and the load increases as the time goes by. Investing a lot of money on hardware would be of waste at first because of resource being utilized. The ideal scenario would be to start with low resources and adjust or increase the CPU/RAM and other resources as and when the need arises. Cloud computing solves this exact problem: You can adjust hardware resources according to the load received by your applications.

Amazon is a popular and reliable vendor providing cloud computing services. The ability to add and remove computing resources through a Web services interface makes the offering more compelling and provides endless integration opportunities. In this document we discuss how you can run WSO2 SOA products on top of computing resources provided by Amazon. This will apply to WSO2 Web Services Application Server (WSO2 WSAS) version 3.1.0, WSO2 Enterprise Service Bus (WSO2 ESB) version 2.1.0, WSO2 Business Process Server (WSO2 BPS) version 1.0.1, WSO2 Governance Registry (WSO2 GReg) version 3.0.0 and WSO2 Identity Server (WSO2 IS) version 2.0.0


There are huge benefits in using Amazon Machine Images (AMIs) over having your own servers and maintaining them. If you're eager to get started with the WSO2 Cloud offerings please feel free to skip to the next section. In this section we will list several advantages of using computing resources provided by Amazon rather than buying your own server to host your applications.

  • Resource upgrades - First and foremost you don't have to worry about keeping up-to-date with the cutting edge hardware platforms. Amazon does it for you. If you need more memory, you don't need to put purchase orders, just upgrade to a more powerful plan.
  • Cost - You don't need to plan ahead with the possible resource requirements your applications need in 2, 3 or 5 years time and invest in a fortune in purchasing powerful server hardware. You can start with a minimum amount of money and pay for the additional resources as you go along.
  • Scalability - As your applications gains more users and processes more transactions the need to scale becomes important. There's a limit to the vertical scaling that you can do to any given computer like the maximum CPU and RAM that's available. Horizontal scaling, adding more machines and distributing the load between them is far more attractive and a cost effective solution. Amazon makes scaling up simpler by adding more machines to an application. Having support for autoscaling with WSO2 products, you can get the benefits for the services you develop as well.
  • Ease of use - We have bundled all WSO2 products into several Amazon Machine Images (AMIs). You can just start those and configure the product through the web interface. In addition to that, you can keep all your configuration data in a separate S3 bucket if you want.

Let's move on to the details of how you can get started.

Getting Started With EC2

The following outlines the steps that should be taken prior to accessing the WSO2 cloud offerings.

Creating an AWS account

In order to use Amazon EC2 offerings, you have to have an account with Amazon Web Services. You can easily create an Amazon Web Services account (AWS) from the Amazon Web Services home page ( You can find more details about creating an AWS account in (

Installing Amazon API tools

Once the AWS account is created, you have to get the Amazon API tools from Amazon EC2 resource center ( This API tools are used as the client interface to manipulate Amazon EC2 instances such as registering and launching instances, manipulate security groups, etc. In order to install these tools, you have to have Java and SSH installed in your machine. You can find more details about the prerequisites in ( and installation guide for the tool in (

Creating key-pairs

When the tools are installed, you have to create a key pair before you can start and use EC2 instances. This keypair is used to login to the EC2 instance without providing a password. One key (private key) will be used in the client (your machine) while the other (public key) is used in the EC2 instance. This is very advantageous and allows you to use many public AMIs where the username and passwords are not configured/known. More information on how to create a key pair and how to use it can be found in (

WSO2 Cloud Offerings

WSO2 products are configured in following AMIs identified at the following location:

Running WSO2 Product AMIs

You can start WSO2 WSAS AMI in an EC2 instance by using the following command:

ec2-run-instances ami-d2a94bbb -k <keypair> -f < file>

Here, ec2-run-instances is a tool provided in Amazon API tool pack. If the command cannot be found, please check PATH variable and see whether Amazon tool pack is configured correctly. The first parameter is the AMI ID of WSO2 WSAS product. (To start other products, give corresponding AMI ID). The second parameter is your keypair you have created in section "Getting started with EC2". EC2 instance will be lauched by embedding public key of the keypair.

The third parameter is an optional parameter where you can pass a payload when starting the EC2 instance. This payload will be used to change some parameters of WSO2 WSAS (or other products) such as administrator username, administrator password, keyfiles used by the product, etc. This parameter should point to a zip file. The zip file should contain 3 files.

  • cert.pem - A PEM encoded signed X.509 certificate
  • pk.pem - An unencrypted, PEM encoded RSA private key that corresponds to the X.509 certificate above
  • launch-params - contains all parameters needs to be passed to the instance at start time.

The first two files are keyfiles used by WSO2 WSAS. The third file contains collection of some other parameters in KEY=value format. It contains some compulsary parameters and some optional ones. Following are the possible KEY and the meaning of the key:

Compulsary parameters:

PRODUCT=<product name>   (WSO2_WSAS, WSO2_ESB, WSO2_BPS, WSO2_GREG, WSO2_IS)
AWS_ACCESS_KEY_ID=<your aws access key id>
AWS_SECRET_ACCESS_KEY=<your aws secret access key>

Optional parameters

REPO_PATH_S3=<s3 bucket name to repository>
REPO_PATH_EBS=<repository path>  and  EBS_VOL_ID=<EBS volume ID>

CONF_PATH_S3=<s3 bucket which contains configuration files>
CONF_PATH_EBS=<path to configuration files> and EBS_VOL_ID=<EBS volume ID>

ADMIN_USERNAME=<admin username>
ADMIN_PASSWORD=<admin password>
LOG_PATH_S3=<s3 bucket name to logs>
LOG_PATH_EBS=<log path> and EBS_VOL_ID=<EBS volume ID>

When the EC2 instance is launched successfully, you can see an output similar to the following:

INSTANCE  <instance-id>  ami-d2a94bbb  pending   keypair   

Instance-id will be something similar to i-10a64379. We can use this instance-id to get more details about the initiated EC2 instance. For example, to access WSO2 WSAS Admin Console, you need to know the public DNS name of the started EC2 instance. You can easily get this detail by using following command:
ec2-describe-instances <instance-id>

For example, "ec2-describe-instances i-10a64379" will give the details about the EC2 instance we just started. The output of above command will be something similar to

RESERVATION     r-fea54097  495219933132  
INSTANCE        i-10a64379  ami-d2a94bbb      running   keypair

In above output, "" is the public DNS of the EC2 instance we have initiated.

Once the instance is successfully started, you can access WSO2 WSAS Management Console using the URL "https:<public dns="" name="">/carbon". As per the example server we have started, URL of WSO2 WSAS Management Console will be:

The default username and password of the management console is "admin" and "admin". If you have specified any ADMIN_USERNAME or ADMIN_PASSWORD in launch-params file, you have to use that username and password. Note that it is strongly recommended to change your admin password the moment you boot up the machine, or better yet by using the configuration file.

Shutting down the instance

If you want to shutdown the instance, you can use following command:

ec2-terminate-instances <instance-id>

In the above example to shutdown the instance what we have started, we have to use "ec2-terminate-instance i-10a64379"


WSO2 AMI offerings has enabled anyone to use enterprise grade SOA products by using Amazon infrastructure without owning any hardware. This enables enterprises to take advantage of WSO2 SOA offerings with minimal cost and scale up to handle heavy loads when their applications attract more users and process many transactions. With a pay-as-you-go model, without any large upfront costs, WSO2 AMI offerings makes it attractive to many individuals and organizations.


Chintana Wilamuna, Senior Software Engineer, WSO2, [email protected]

About Author

  • Chintana Wilamuna
  • Architect
  • WSO2