Installing WSO2 Products On Linux , Windows or Mac

The three main products from WSO2: API Manager, Identity Server and Micro Integrator can quickly be installed on your local computer. In this blog we will describe the general installation procedure which is the same for all three on Windows, Linux or Mac. We will do this with Micro Integrator as an example within the final paragraph instructions for the other two products.

When you want to try out  using Micro Integrator (MI) in order to see what the product can do it is easy to install on your local machine. WSO2 software is what we call ‘any prem’, it can run locally, it can run in the cloud, and it can run on your server which is a big benefit. It does not matter if you install it on Linux, Windows or Mac.

Actually, a lot is the same for both environments. Like the download of the binary files, setting of Java et cetera.

On all three platforms, installation is quite easy and can be done in a couple of minutes. Of course, I am not talking about a REAL installation where you configure WSO2 MI for production or even a Proof of Concept. No, I am talking about installing to quickly try out one of the mediations from one of our blogs for example.

Open Source or Product Support

What are the choices that you have? Well first of all the choice of version. Do you go with the open-source version that you can download from GitHub, or do you use the version that you can download from the website of WSO2 which is not open source but requires a product support license when you use it in production. I suggest that you read the EULA terms when you download the file to decide what is best for you.

Client Case Gebrüder Weiss

WSO2 API Manager helps to standardize communication with their customers

Download now

But let us get back to the source code. You can find it here and since a couple of months WSO2 does not post the binaries anymore but only the source code. You simply download the source code but in order to use it, a Maven Build is required to create the binary files. This in a sense is not much work, 23 minutes as you can see from the screenshot. Maven is the build tool to build the product from the source, I will not go into too much detail about this process, you will find a number of blogs about building from source on the Yenlo website.

If this looks like too much work and you do not want to be bothered by this, I suggest that you download the version from WSO2. The Micro Integrator can be found on the Integration section of the site. The documentation, however, is still with the API Manager as for the last couple of versions the Micro Integrator was only accessible via API Management download page. Does that make sense? Yes and no. The API Manager and the Micro Integrator are siblings and work together well, although they are different products with different use cases.

Go to this URL to download : https://wso2.com/micro-integrator/

Click Download.

Enter a corporate e-mail, meaning one that is considered a business e-mail so not like Gmail or other free e-mail services. Accept the software license. The download is not instant, you will get a link for a one time download of the zip file. If you want to download it a second time,  you need to repeat the process. You will receive an email in which you will find a download button to click.

This starts the download of the zip file. You will find it in the downloads folder of your computer and in order to continue with the installation we are going to copy it to the desktop. If you have done that create a directory called MI420. Use your archive or zip manager to extract the zip file into that directory. I am showing the Linux Download, for Windows the principle is the same.

Until now all the instructions are agnostic of the operating system. From this point on we are going to show the configuration for the Linux environment. In this case our CentOS environment. When something is different for Windows or Mac. We will indicate the differences.

It will look like this.

What we need to do is to download JAVA as well. You might already have a Java version on your machine but in this case I am going to download JDK17 since MI 4.2.0 supports that version (as well as Java 11).

The list actually mentions the following JDKs.

I will download the Adopt OpenJDK as a zip file. After Download, please also unpack in the MI420 directory.

The directory now looks like this.

Now we are going to create a batch file that will temporarily set JAVA_HOME and extend the PATH to use the version of Java in our directory. This means that it does not interfere with any other versions that you might have since the settings only last for the duration of the running batch file.

The code is actually quite simple.

This is the code for Linux:

export OLDPATH=$PATH

export OLDJH=$JAVA_HOME

echo Setting JAVA_HOME

export "JAVA_HOME=/opt/wso2/Desktop/MI420/jdk-17.0.7+7"

echo JAVA_HOME: $JAVA_HOME

echo Setting PATH

export "PATH=/opt/wso2/Desktop/MI420/jdk-17.0.7+7/bin;$PATH"

echo PATH: $PATH

echo starting WSO2 MI 4.2.0

cd /opt/wso2/Desktop/MI420/wso2mi-4.2.0/bin

sh micro-integrator.sh

cd ../..

export PATH=$OLDPATH

export JAVA_HOME=$OLDJH

echo JAVA_HOME: $JAVA_HOME

echo Done

For Windows, the script is a bit different, but not much. Mostly in the way Windows works with directories, like the backslash rather than forward slash.

@set OLDPATH=%PATH%

@set OLDJH=%JAVA_HOME%

@echo Setting JAVA_HOME

@SET "JAVA_HOME=C:\Users\rob\Desktop\MI420\jdk-17.0.7+7"

@echo JAVA_HOME: %JAVA_HOME%

@echo Setting PATH

@SET "PATH=C:\Users\rob\Desktop\MI420\jdk-17.0.7+7\bin;%PATH%"

@echo PATH: %PATH%

@echo starting WSO2 MI 4.2.0

@cd C:\Users\rob\Desktop\MI420\wso2mi-4.2.0\bin

@start micro-integrator.bat

@cd ..\..

@set PATH=%OLDPATH%

@set JAVA_HOME=%OLDJH%

@echo JAVA_HOME: %JAVA_HOME%

@echo Done

When you run the script from a terminal this is what it looks like on Linux.

As you can see, JAVA HOME is not affected, only within the terminal it is set. The code actually restores the old settings of path and JAVA_HOME.

Installing on Windows

For Windows, the best way to start Micro Integrator is to open a CMD window rather than clicking on the icon in the regular folder view. When something goes wrong, in a CMD window you can see the message, when you click, and something goes wrong it closes directly without the opportunity to see what went wrong.

Installing on Mac

On Mac the script is similar to Linux, but the path of Java home is different as the directory structure of the downloaded JDK of Mac.

This is the code for Mac:

export OLDPATH=$PATH

export OLDJH=$JAVA_HOME

echo Setting JAVA_HOME

export "JAVA_HOME=/Users/rob/Desktop/MI420/jdk-17.0.7+7/Contents/Home"

echo JAVA_HOME: $JAVA_HOME

echo Setting PATH

export "PATH=/Users/rob/Desktop/MI420/jdk-17.0.7+7/Contents/Home;$PATH"

echo PATH: $PATH

echo starting WSO2 MI 4.2.0

cd /Users/rob/Desktop/MI420/wso2mi-4.2.0/bin

sh micro-integrator.sh

cd ../..

export PATH=$OLDPATH

export JAVA_HOME=$OLDJH

echo JAVA_HOME: $JAVA_HOME

echo Done

When you run the script from a terminal this is what it looks like on Mac.

Testing it

So that is the installation of the Micro Integrator on your local machine. How do we know that it works? Well, we can put a simple API on the Micro Integrator. I will not use Integration Studio but rather let you create an XML Synapse configuration and copy that directly into the Synapse Config directory.

The API will use the icanhazdadjoke.com API that is exposed there and will return a joke.

Copy this code to an xml file called joke.xml and store it in a directory called api. This directory is not there yet, so you need to create it.

<?xml version="1.0" encoding="UTF-8"?>

<api context="/joke" name="joke" xmlns="http://ws.apache.org/ns/synapse">

    <resource methods="GET">

        <inSequence>

            <property action="remove" name="REST_URL_POSTFIX" scope="axis2"/>

            <header name="Accept" scope="transport" value="application/json"/>

            <call>

                <endpoint>

                    <http uri-template="https://icanhazdadjoke.com/">

                        <suspendOnFailure>

                            <initialDuration>-1</initialDuration>

                            <progressionFactor>-1</progressionFactor>

                            <maximumDuration>0</maximumDuration>

                        </suspendOnFailure>

                        <markForSuspension>

                            <retriesBeforeSuspension>0</retriesBeforeSuspension>

                        </markForSuspension>

                    </http>

                </endpoint>

            </call>

            <respond/>

        </inSequence>

        <outSequence/>

        <faultSequence/>

    </resource>

</api>

This is where you need to create it. [MI-HOME]/repository/deployment/server/synapse-configs/default/api.

Dropping the file there will be enough. MI will read and deploy.

Now open a browser window and copy this url

http://localhost:8290/joke

The API we deployed will respond with a joke.

This is quite a quick and dirty way of deploying an API. Normally we would create an integration project in Integration Studio and deploy the API with a Composite Exporter. However, for a quick test like this  it works just fine and does not require installation and explanation of Integration Studio to see whether the product works.

Brochure Integration solutions with WSO2

A vendor summary

Download now

Installing other WSO2 Products

The API Manager and Identity server can be installed in a similar manner. The differences are of course:

• the download location for the Products, this is for API Manager and this for Identity Server
• within the individual scripts the name of the directories (i.e., wso2am-4.2.0 and wso2is-6.1.0) and startup commands (api-manager.sh/bat wso2server.sh/bat)

A quick example for the API Manager on Windows with the changes as opposed to Micro Integrator in Yellow;

@set OLDPATH=%PATH%

@set OLDJH=%JAVA_HOME%

@echo Setting JAVA_HOME

@SET "JAVA_HOME=C:\Users\rob\Desktop\AM420\jdk-17.0.7+7"

@echo JAVA_HOME: %JAVA_HOME%

@echo Setting PATH

@SET "PATH=C:\Users\rob\Desktop\AM420\jdk-17.0.7+7\bin;%PATH%"

@echo PATH: %PATH%

@echo starting WSO2 AM 4.2.0

@cd C:\Users\rob\Desktop\MI420\wso2am-4.2.0\bin

@start api-manager.bat

@cd ..\..

@set PATH=%OLDPATH%

@set JAVA_HOME=%OLDJH%

@echo JAVA_HOME: %JAVA_HOME%

Of course, there are more options like running it in a container. That might be a nice topic for an upcoming blog.

Thanks to Saad Sahibjan for his help on the Mac