Getting Started: What is WSO2 and how to install it?

Perhaps it is a little bit too early to congratulate you with your choice for WSO2. You might be interested in learning a bit more about the platform and perhaps installing it to take a look (we advise you to do so). This document will give a bit of background on integration, WSO2 and the Enterprise Service Bus (WSO2 ESB) as well as show you how easy it is to install one of the WSO2 components and access its management console.

Mind you, installation is not the same as implementation. Implementation within your organization is something that requires more effort.

WSO2 vs. other solutions

Figure 1 Magic Quadrant for
On-Premises Application Suites

Of course there are other ESB solutions on the market, both from commercial vendors like IBM, Microsoft, Tibco Software, Software AG and Oracle as well as smaller vendors like Talend, Infor or Fiorano and open source software (OSS) vendors like MuleSoft.

In July of 2014, Gartner updated the Magic Quadrant for On-Premises Application Suites and WSO2 is positioned in the Visionaries Quadrant. In our opinion that is correct, WSO2 has a very strong suite of products that is now gaining recognition in the market being deployed more and more by large (e.g. Fortune 500) companies and we believe it is a matter of time before WSO2 enters the Leaders Quadrant.

If you are interested in the complete report (20+ pages) please go to the WSO2 website to download it.

Required knowledge

Do you need to be an expert to read and understand this document? No, not an expert. Some computer knowledge is required, but not a lot.

Figure 2 Integration is like a puzzle
(CC Flickr Horia Varlan)

We will start off with explaining the need for integration, talk a bit about the WSO2 components and finish with how to install one of the components and access its management console.

The need for integration

Soon after the first computer programs were written the need for information or data exchange or even integration was born. At first data exchange or integration was quite unsophisticated: for instance a text file was created by one program and subsequently read by another.

In some cases a program would print out a list and a data typist would enter the data in the next system or program. In some cases direct connections were made, one program calling the other.

All of these types of connections were more exchange of data than integration of systems. More and more computer programs became available, developed by organizations as well as by third party vendors increasing the need to exchange information in an efficient way.

The next step message brokers and message oriented middleware

A logical next step are message brokers and message oriented middleware. Exchanging data between applications was viewed as messages that are sent from one application or system to another. Much like the idea of a postman, the message broker is a program that takes care of message delivery, more specifically message validation, message transformation and message routing.

Message Oriented middleware (MOM) is, like the name suggests software that resides between the operating system and the application layer and supports sending and receiving messages between distributed systems. It allows applications to be distributed over heterogeneous platforms. With that we mean the typical ICT landscape that consists of all models and makes of computers and version of software that was never intended to work together but nevertheless should.

MOM makes it easier to develop applications that span multiple systems, inside or outside your organization. A message broker is part of the suite of tools of MOM (as well as WSO2).

The term Message Oriented Middleware is not used much nowadays. The term Enterprise Service Bus is more or less the successor to MOM building on many of its principles.

Enterprise Service Bus

Figure 3 ESB Model (Wiki CC
Silver Spoon)

An enterprise service bus (ESB) is not a product but a software architecture model, describing the way applications or components communicate. The communication typically takes place in a service-oriented architecture (SOA) where each application or component provides or propagates its services.

An example of such a service is a component that can validate an account number to see if it is a valid international banking account number (IBAN). This service can be used by many other components and rather than making direct calls from the component to the IBAN component the ESB acts as a central hub (you might even call it a traffic cop) and directs requests to the IBAN component, optionally taking care of converting the information to the needed format.

Forty years of ICT development has created an ICT landscape that in inherently heterogeneous. The advent of mobile devices, the Bring Your Own Device movement, Internet of Things and Big Data have made the case for an Enterprise Service Bus solution even more compelling offering the components you need to take advantage of the opportunities on offer by these new technologies.

That is where WSO2 comes in.

What WSO2 offers

Figure 4 WSO2 screenshot (www.WSO2.com)

WSO2 calls itself an open platform for connected business. WSO2 is completely open source built on industry standard solutions and technology like Java, Apache and so on. It offers everything you can imagine you would need in today’s and tomorrow’s business world.

You can download and start using it without incurring any license fees or intense contract negotiations with lawyers, just download, install and go ahead. WSO2 is not one big program but consists of a number of components that each performs a special task and can be tightly integrated.

We are working on a WSO2 Component Selection Tool (WCST) that will guide you in selecting the components you need or might need based on your Business-, IT- or Technology challenges. Furthermore we will describe each of the components and its functions in separate articles on the yenlo.com website For now, since both are not ready yet, please look at the list from the WSO2 website in which a high-level description is provided. If you have any questions please contact us with any questions.

Getting started Downloading and Installing WSO2 components

Let’s say that you identified the component that you need and it the API manager. Where would you find it? All the latest versions of WSO2 components should be downloaded from the WSO2 website.

Why? Because you will find the latest versions and also have the supporting documentation, source files and everything else. Get it from the source, the people who developed it. That is of course always best.

Just go to the WSO2 website and under Products, Middleware Platform you will find all the components.

Preparing for installation

There are a number of prerequisites that you should adhere to if you want to install WSO2 components.

We have made a quick overview of what is generally needed. Please look at the support documentation for each component for more information on additional components.

Required files for installing WSO2 products

In order to run WSO2 you need the JDK that you can download for free from Oracle. There are some incompatibilities between WSO2 and JDK 8 so for now (September 2014) it is best to download version JDK version 7 rather than JDK version 8.

Please select the version that it right for you. Install the JDK and set the JAVA_HOME environment variable with the right drive and path, e.g. D:javajdk1.7.0_67.

Figure 5 Setting the JAVA_HOME
environment variable

In general, if you have any questions about the compatibility of your environment (OS/DBMS/AS) you can contact us.

Supported operating systems

You will be happy to know that as all of WSO2 products are Java applications you can, in general, run them on most operating systems like Windows, Linux, Solaris, Ubuntu, SUSE, Mac OS X and so on when you also have a Java Development Kit runtime (version 1.6.x or 1.7.*). For a list of supported, tested or compatible OS, see the WSO2 website.

Supported database management systems (DBMS)

WSO2 products are generally compatible with the most common and often used DBMS like MySQL, MS SQL Server, Oracle, H2, DB2 and Derby.

Supported Application Servers

WSO2 products are generally compatible with the most common and often used application servers like Tomcat, JBoss, WebLogic and WebSphere.

Build from source code or use binaries?

With WSO2 you have the choice to either build the product from the source code or use the binary files that are included in the distribution zip file.

If you are new to WSO2 we would suggest starting with the binaries. Although compiling the source code is not rocket science it does require some skill and knowledge of the WSO2 helps in that case.

We have made a quick overview of what is generally needed. Please look at the support documentation for each component for more information on additional components.

Required files for installing WSO2 products

Furthermore, if you want to use the Java Message Service functionality Apache ActiveMQ JMS Provider (or equivalent) is required. To compile and run the product samples Apache Ant is needed.

Required memory, heap size and disk space

On average the minimum required memory to run WSO2 components is 2GB. The minimal heap size is 512 MB (only the ESB needs 1 GB) and required disk size (excluding space allocated for log files and databases) varies from 180 MB to 1 GB on average. The only exception is the Message Broker, there the disk size depends on the number of messages since they are stored on disk.

Memory size and disc space requirements WSO2 products

Getting ready to run in 4 steps

Installing any of the WSO2 components follows the same path and procedure. We describe the installation of the binary files here for Windows Operating System, not the compilation of source files:

Figure 6 Structure of the WSO2 API Manager directory

1. Install the JDK and set the JAVA_HOME directory with the disk and path where you installed the JDK;

2. Download the binary file from the WSO2 site (or the sources if you want to compile them);

3. Unpack or unzip the downloaded file in the directory you want to run it (e.g. c:WSO2API_MGR;

4. Go to c:WSO2API_MGRBIN and run the WSO2server.bat file;

We presume you have taken step 1 and downloaded the JDK and set the JAVA_HOME variable and also downloaded the binary file from the WSO2 website.

Installing the WSO2 component

Figure 1 Security warning when
running the wso2server.bat

The downloaded file is a so called zip file that is a packaged collection of all necessary files in the right directories. Extract the file for instance by clicking the right mouse button and selecting extract here or double click the file and extract to the target directory where you want to install it.

Go to the bin directory and double click the file WSO2server.bat.

Security warning

You might get a security warning like the one shown in fig. 1. In this case you can run the file since you trust the publisher.

Opening command window

A so called command window will open and will start the API Manager component. It looks technical (and it is) but not to worry, the only thing of interest now is the address of the management console. You can find it in the line that shows ‘… Mgt Console URL’. In this example it’s https://192.168.2.10:9443/carbon.

Starting the management console

Figure 8 The Command window that is opened when the WSO2server.bat is run

If you copy that line into your web browser and your WSO2 server is running in the command window you can start the Management Console. If you get any messages about certificates, please continue to the URL. You are running on your own PC so the risk is low. The message simply informs you that the certificate is not issued by a trusted Certificate Authority like Verisign , since you are running locally this is not an issue.

Figure 7 Message about the certificates

Please be informed that if you get this message on the internet it might be wise to follow the instructions and not continue to the website.

If you continue to the site, you are shown the default login screen. After logging in with the default ID

Figure 2 Default login screen for the management console

‘admin’ and Password ‘admin’ (without the quotes), you get the following screen.

Figure 9 Management Console for WSO2 API Manager

We can now congratulate you, you have successfully downloaded and installed WSO2 API Manager.

Running multiple WSO2 products on the same server

The default port management console of each WSO2 product is always the same. So if you running multiple WSO2 components on the same server, what you need to do is change the port offset in the configuration file (carbon.xml) so that they will point to a different port and you can access all management consoles.

In order to do so you go to the directory in which the product was installed, go to the /repository/conf/directory and open the carbon.xml file and change the value to 1 or whatever value you would like.

The default is of course zero ,which corresponds to the port of 9443. If you change the offset value in the XML file to 1 it is of going to be https://192.168.2.10:9444/carbon and so on.

What you need to keep in mind when running several WS two products at the same server is the amount of memory that you going to need. You can look up in the amount of memory that is needed in the table introduced earlier. In many cases it is 2 GB with the heap size of about 512 MB memory as well for almost each product.

If you do find that the performance is going to beat this is sluggish then you’re better off moving it to different servers.