WSO2 ESB - Installation Guide [ Documentation Index ]

WSO2 Enterprise Service Bus (ESB) Installation Guide

This installation guide provides information on,

  1. the prerequisites for WSO2 ESB
  2. installation instructions
  3. starting up WSO2 ESB, and
  4. accessing the management console

This document describes the distribution packages available in WSO2 ESB - the binary distribution and the source distribution for more advanced users. It is followed by simple instructions on how to install and run WSO2 ESB using the binary distribution and how to build WSO2 ESB using the source distribution.

Contents

Distribution Packages

The following distribution packages are available for download.

1. Binary Distribution : Includes binary files for both MS Windows and Linux operating systems, compressed into a single a zip file. Recommended for normal users.

2. Source Distribution : Includes the source code for both MS Windows and Linux operating systems, compressed into a single zip file which can be used to build the binary files. Recommended for more advanced users.

Installing and Running WSO2 ESB using the Binary Distribution

Prerequisites

Java SE Development Kit 1.5.x (For instructions on setting up the JDK on different operating systems, visit http://java.sun.com)

To build WSO2 ESB from the Source distribution, it is necessary that you have JDK 1.5.x version and Maven 2.1.0 or later

Apache ActiveMQ -JMS Provider

Apache ActiveMQ 4.1.0 or higher is required to enable the WSO2 ESB JMS transport and try out JMS samples. The ActiveMQ client libraries must be installed in the ESB classpath before you can enable the JMS transport.

If you are using any other JMS provider (eg: Apache Qpid), you will need to install any necessary libraries and/or any components.

Apache Ant - To run ESB samples

To compile and run the sample clients, an Ant version is required. Ant 1.7.0 version is recommended.

Apache Maven- To build ESB from Source To build the WSO2 ESB from its source distribution, you will need Maven 2.1.2 or later
Web browser- To start the ESB Management Console Mozilla Firefox 3.0 at a resolution of 1024x768 is recommended. MS Internet Explorer 7 may be used as well, with some minor limitations. Once the WSO2 ESB is started point the browser to https://localhost:9443/carbon in order to access your Management Console. See the WSO2 ESB User Guide for more details.
Memory No minimum requirement - A heap size of 256~512MB is generally sufficient to process typical SOAP messages. Requirements may vary with larger message size and on the number of messages processed concurrently
Disk No minimum requirement. The installation will require ~125 MB excluding space allocated for log files and Databases.
Operating System Linux, Solaris, MS Windows - XP/ Vista (Not fully tested on Windows Vista). Since WSO2 ESB is a Java application, it will generally be possible to run it on other operating systems with a JDK 1.5.x runtime. Linux/Solaris is recommended for a production deployment.

Installing on Linux/Unix

The following steps will take you through the binary distribution installation on Unix/Linux systems.

  1. Download the WSO2 ESB binary distribution.
  2. Extract the zip archive where you want the WSO2 ESB installed (e.g. into /opt)
  3. Set the JAVA_HOME environment variable to your Java home using the export command or by editing /etc/profile, and add the Java /bin directory to your PATH
  4. Execute the WSO2 ESB start script or the daemon script from the bin directory. e.g. ./wso2server.sh OR ./daemon.sh start OR ./wso2server.sh --console
  5. Check your WSO2 ESB instance using the URL https://localhost:9443/carbon which will take you to the WSO2 ESB Management Console. (Note that server start up may take time)
  6. Login as "admin" using the default password "admin"

Installing on MS Windows

The following steps will take you through the installation for the MS Windows operating system.

  1. Download the WSO2 ESB binary distribution.
  2. Extract the zip archive where you want the WSO2 ESB installed
  3. Set the JAVA_HOME environment variable to your Java installation, and the PATH environment variable to the Java /bin directory.
  4. Execute the WSO2 ESB start script from the bin folder. e.g. wso2server.bat
  5. If you would like to install the WSO2 ESB as a Windows service, use the install.bat script
  6. Check your WSO2 ESB instance using the URL https://localhost:9443/carbon which will take you to the WSO2 ESB Management Console.
  7. Login as "admin" using the default password "admin"

Building WSO2 ESB Using the Source Distribution

Prerequisites

Java SE Development Kit 1.5.x (For instructions on setting up the JDK in different operating systems, visit http://java.sun.com)
Apache Maven- To build ESB from Source To build the WSO2 ESB from its source distribution, you will need Maven 2.1.0 or later
Operating System Linux, Solaris, MS Windows - XP/ Vista (Not fully tested on Windows Vista)

Setting up the Environment and Tools

Maven:

The WSO2 ESB build is based on Apache Maven 2. Hence, it is a prerequisite to have Maven (version 2.1.0 or later) and JDK (version 1.5.x) installed in order to build WSO2 ESB from the source distribution. Extensive instructions on using Maven 2 are available on the Maven website.

Please refer to the Maven Getting Started Guide for more information on Maven

  1. Download Apache Maven tar ball or the zip archive.
  2. Expand it to a directory of choice.
  3. Set the environment variable M2_HOME and add M2_HOME/bin to the path as well.
  4. Run mvn --version to verify that it is correctly installed.
  1. Download and run the Apache Maven Windows installer package.
  2. Set the 'Environment Variables' (create the system variable M2_HOME and edit the path. e.g., "C:\Program Files\Apache Software Foundation\maven-2.0.6"; path %M2_HOME%\bin)
  3. Make sure that the system variable JAVA_HOME is set to the location of your JDK, e.g., C:\Program Files\Java\jdk1.5
  4. Run mvn --version to verify that it is correctly installed.

Once Maven is properly installed, you can start building the WSO2 ESB.

Building WSO2 ESB

  1. Download the source distribution, which is available as a zip archive. (Note: this contains the full carbon platform source not just the ESB)
  2. Expand the source archive to a directory of your choice.
  3. All the necessary build scripts are included with the source distribution.
  4. You can run the following command inside any project directory to build the WSO2 ESB. Note that you will require a connection to the Internet for the Maven build to download dependencies required for the build.
    Command: mvn clean install
  5. Alternatively, if you need to build the complete platform with the ESB there is a "build.sh" script available at the root of the source distribution. You could pass in any maven option to this script but the test skipping command has been shortened to "-ts"

This will create the complete release artifacts including the binary and source distributions in the product/modules/distribution/target/ directory which can be installed using the above instructions.

Note: The first time you run Maven it will automatically download the dependent .jar files. Therefore, the first run will take more time.