[Download] | [Documentation Home] | [Release Note]

Installation Guide

This installation guide provides information on,

  1. the prerequisites for WSO2 WSAS
  2. installation instructions
  3. starting up WSO2 WSAS, and
  4. accessing the management console
Of the two main sections of this document, one explains the installation of the WSO2 WSAS in Standalone Mode, while the other explains the installation of the WSO2 WSAS into a J2EE compliant servlet container. For the more adventurous user, WSO2 WSAS can also be built using the source distribution available with this release. The third section of this installation guide explains how to build WSO2 WSAS using the source distribution. Your feedback on WSO2 WSAS is most appreciated. Please send them to our mailing lists.

Content

Introduction

WSO2 WSAS is a lightweight application server for Web services. It is built on the Apache Axis2 framework and incorporates leading open source components into a simple, easy-to-use, and highly performant package. Web services specifications support include WS-Addressing, WS-Policy, WS-ReliableMessaging, WS-Security and more, giving a fully secure, transactional and reliable infrastructure. WSO2 WSAS is distributed in several convenient distribution packages, and can be installed either as a standalone server or as part of a J2EE compliant servlet container. WSO2 WSAS is distributed under the Apache License, version 2.0. [Download WSO2 WSAS ]

System Requirements

Java Runtime Environment 1.4 or 1.5 (For instructions on setting up the JRE in different operating systems, visit http://java.sun.com)
Memory No minimum requirement
Disk No minimum requirement. Approximately 40 MB will be used for the .zip distribution
Operating System Tested on Windows XP, Linux, Mac OS X, Fedora core, Ubuntu, Gentoo

Installing WSO2 Web Services Application Server v2.1 in the Standalone Mode

Installing on Microsoft Windows

Note: The WSO2 WSAS, v2.1 release has been successfully tested only on Windows XP. There are two methods of installation on the MS Windows operating system.
  1. Using the Installation Wizard (WSO2 WSAS for Java, v2.1 Setup wizard)
  2. Using the Binary Distribution

Running the Installation Wizard

Download the wso2wsas-2.1.msi Execute the .msi and follow the instructions on the WSO2 WSAS , v2.1 Setup wizard The first page of the installation wizard is as follows.



Figure1:Installation Wizard Page1



Click Next. It will lead you to the End-User License Agreement.



Figure2:Installation Wizard Page2-EULA



Select the check box to accept the terms in the license agreement; this will enable the Next button. Click Next to move to the Custom Setup page shown below. Custom Setup will allow you to select the features you want to install.



Figure2:Installation Wizard Page3-Custom





On the next screen you'll be shown the custom installation features select section.



Figure2:Installation Wizard Page3-Browse for Location



Click Next on the Custom Setup Page to move to the Ready to Install page displayed below. Click Install. WSO2 WSAS, v2.1 will be installed in your computer.



Figure6:Installation Wizard Page5-Ready to install



Once the installation is complete and the setup exits, click Finish on the WSAS setup wizard. You willl be able to view WSO2 WSAS on the programs list of the Start menu of Windows. A shortcut to WSO2 WSAS , v2.1 will also appear on the Desktop. On the programs list of the Start menu, WSO2 WSAS will have the following options :



Figure7:Programme on start menu



Once you add WSO2 WSAS as an NT service to Windows services, you can start this service from Services in Administrative tools of the Control Panel.



Figure8:Network service



Installing using Binary Distribution

The following steps will take you through the installation for the MS Windows operating system.
  1. Download the WSO2 WSAS binary distribution.
  2. Extract the zip archive.
  3. Set the JAVA_HOME environment variable to your Java installation.
  4. Execute the WSO2 WSAS starting script. e.g., C:\wso2wsas-2.1\bin\wso2wsas.bat
  5. Check your WSO2 WSAS instance using the URL https://localhost:9443

Installing on Linux

Again, there are two methods of installing on Linux:
  1. Using Binary Distribution
  2. Using Binary Installers (deb/rpm)

Installing using Binary Distribution

  1. Download the WSO2 WSAS binary distribution.
  2. Extract the zip archive. e.g., unzip wso2wsas-2.1.zip -d /opt
  3. Set the JAVA_HOME environment variable to your Java installation using the export command or by editing /etc/profile. e.g., export JAVA_HOME="/opt/j2sdk"
  4. Execute the WSO2 WSAS starting script. e.g., cd /opt/wso2wsas-2.1/bin; sh wso2wsas.sh
  5. Check your WSO2 WSAS instance using the URL https://localhost:9443

Installing using Binary Installers (deb/rpm)

The following steps will take you through the binary distribution installation.
  1. Download WSO2 WSAS deb or RPM binary.
  2. Install Debian binary ( deb ) e.g., dpkg -i wso2wsas-java-2.1.deb (To install deb, log on to the system as root user.)
  3. Install RPM binary ( rpm ) e.g., rpm -Uvh wso2wsas-java-2.1.i386.rpm (To install rpm, log on to the system as root user.)
  4. Execute/start the WSO2 WSAS from the shell. e.g., /etc/init.d/wso2wsas start.

    (You can also stop the server from the shell. e.g., /etc/init.d/wso2wsas stop)

Troubleshooting Installation

When trying to execute the WSO2 WSAS binary from a shell, e.g., /usr/bin/wso2wsas (after WSO2 WSAS , v2.1 has been installed), if the error message 'Permission denied' pops up, then check the file permission of the run.sh script and set the execution permission.

Modify/ Repair/ Remove Installation

On MS Windows systems,



Figure9:modify_repair_remove



In Debian Linux systems, use the dpkg utility to remove the WSO2 WSAS installation. e.g., dpkg -r wso2wsas-java-2.1 In Redhat Linux systems, use the rpm utility to remove the WSO2 WSAS installation. e.g.,: rpm -e wso2wsas-java-2.1

Accessing the Management Console

Once WSO2 WSAS , v2.1 has been successfully installed, in order to access the Management Console, first start the server, launch a web browser instance, and then point it to the URL https://localhost:9443/ (if you are using the default settings). This will take you to the "Sign In" page of the Management Console as displayed below. Note: By default, WSO2 WSAS has two listeners, HTTP and HTTPS. The HTTP listener opens on port 9762, while the HTTPS listener opens on port 9443. The administrator functions are exposed only via the HTTPS port.



Figure10:mgtconsole



For details on WSO2 WSAS Management Console see the Administrator's Guide

Installing WSO2 Web Services Application Server, v2.1 in a Servlet Container

This section provides instructions on how to install the WSO2 WSAS in a Servlet container. This also includes information on how to configure WSO2 WSAS on JBoss, Geronimo and Tomcat servers. Some guidelines on installing WSO2 WSAS on other application servers have also been included. Your feedback on WSO2 WSAS is most appreciated. Please send them to our mailing lists.

Introduction

The WSO2 WSAS Servlet should be installed on a J2EE compliant servlet container. WSO2 WSAS has been fully tested on the following J2EE Application Servers, and specific installation instructions for each server are listed under the Application Server Specific Installation section.

J2EE Application Servers

Apache Tomcat Server: JBoss AS: Apache Geronimo AS: BEA WebLogic AS General: Web application servers that do not fall under the above list will have to follow the Generic Application Server Installation Steps described below.

Application Server Specific Information

Installation Instructions

Follow the simple installation steps to successfully install WSO2 WSAS into a JBoss AS, Apache Geronimo AS or Apache Tomcat server. 1. Download the WSO2 WSAS binary distribution if you haven't done so. Download Unzip wso2wsas-2.1.zip to a desired location. (eg: c:\wso2-wsas on windows or /home/wso2wsas on linux). This folder will be referred to as WSO2WSAS_HOME. 2. Run install.sh for Linux or install.bat for MS Windows from WSO2WSAS_HOME/bin 3. Select the WSO2WSAS_HOME. 4. Select the application server and its version. 5. After this point, there are a few application server specific steps to be followed: Apache Tomcat Server: JBoss AS: Some specific libraries and application server specific files will be copied to the relevant directories. 7. Restart the application server. Now the Management Console should be available on https://localhost:9443/wso2wsas if you used the default settings.

Advanced Configuration Instructions

We support the following Application Servers out of the box with our installer. However, if you wish to manually carry out the configuration, the following tips will be helpful:

Apache Tomcat Server:

a) Version 5.5.x 1. Enabling SSL on Tomcat To enable SSL on Tomcat 5.5.x the server XML should contain the following segment:
  <Connector port="9443" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25"
   maxSpareThreads="75" 
   enableLookups="false" disableUploadTimeout="true" 
   acceptCount="100" scheme="https" secure="true"
   clientAuth="false" sslProtocol="TLS"
   keystoreFile="wso2wsas/conf/wso2wsas.jks"
   keystorePass="wso2wsas" />
NOTE: You can use any keystoreFile of your preference instead of the wso2wsas.jks which is shipped with WSO2 WSAS.

2. Registering the WSO2 WSAS Data Store

To register the data source, include the following segment in the server.xml within the 'host' element

<Context path="/wso2wsas" >
  <Resource name="jdbc/wso2wsas_db"
    auth="Container"
    type="javax.sql.DataSource"
    maxActive="100"
    maxIdle="30"
    maxWait="10000"
    username="wso2wsas"
    password="wso2wsas"
    driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
    url="jdbc:derby:../database/WSO2WSAS_DB"/>
</Context>

b) Version 5.0.x

1. Enabling SSL on Tomcat

To enable SSL on Tomcat 5.0.x the server XML should contain the following segment

<Connector port="9443"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" debug="0" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="wso2wsas/conf/wso2wsas.jks"
keystorePass="wso2wsas />

NOTE: You can use any keystoreFile of your preference instead of the wso2wsas.jks which is shipped with WSO2 WSAS.

2. Registering the WSO2 WSAS Data Store

To register the data store, include the following segment in the server.xml within the 'host' element

<Context path="/wso2wsas" docBase="wso2wsas"
 reloadable="true" crossContext="true">
   <Resource name="jdbc/wso2wsas_db" auth="Container"
    type="javax.sql.DataSource"/>
      <ResourceParams name="jdbc/wso2wsas_db">
        <parameter><name>username</name><value>wso2wsas</value></parameter>
        <parameter><name>password</name><value>wso2wsas</value></parameter>
        <parameter><name>driverClassName</name>
        <value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
        <parameter><name>url</name>
        <value>jdbc:derby:../database/WSO2WSAS_DB</value>
        </parameter>
   </ResourceParams>
</Context>

c) Version 4.1.x

1. Enabling SSL on Tomcat

To enable SSL on Tomcat 4.1.x the server.xml should contain the following segment

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
 port="9443" minProcessors="5" maxProcessors="75"
 enableLookups="true" 
 acceptCount="100" debug="0"
 scheme="https"
 secure="true"
 useURIValidationHack="false"
 disableUploadTimeout="true">
   <Factory
    className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
    keystoreFile="wso2wsas/conf/wso2wsas.jks"
    keystorePass="wso2wsas"
    clientAuth="false" protocol="TLS" />
</Connector>

NOTE: You can use any keystoreFile of your preference instead of the wso2wsas.jks which is shipped with WSO2 WSAS .

2. Registering the WSO2 WSAS Data Store

To register the wso2 wsas data store, include the following segment in the server.xml within the 'host' element

<Context path="/wso2wsas" docBase="wso2wsas"
 reloadable="true" crossContext="true">
   <Resource name="jdbc/wso2wsas_db" auth="Container"
    type="javax.sql.DataSource"/>
    <ResourceParams name="jdbc/wso2wsas_db">
      <parameter><name>username</name><value>wso2wsas</value></parameter>
      <parameter><name>password</name><value>wso2wsas</value></parameter>
      <parameter><name>driverClassName</name>
        <value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
      <parameter><name>url</name>
        <value>jdbc:derby:../database/WSO2WSAS_DB</value>
      </parameter>
   </ResourceParams>
</Context>

2. JBoss AS

Version 3.2.x and 4.0.x

1. Enabling SSL on JBoss

To enable SSL on JBoss, add the following segment to JBOSS_HOME/server/default/deploy/jbossweb-tomcatxx.sar/server.xml as a child of the jboss.web Service element.

<Connector port="9443" address="${jboss.bind.address}"
 maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
 emptySessionPath="true"
 scheme="https" secure="true" clientAuth="false"
 keystoreFile="${jboss.server.home.dir}/tmp/wso2wsas/conf/wso2wsas.jks"
 keystorePass="wso2wsas" sslProtocol = "TLS" />

NOTE: You can use any keystoreFile of your preference instead of the wso2wsas.jks which is shipped with WSO2 WSAS.

2. Registering the WSO2 WSAS Data Source

To register the data source, create the wso2wsas-derby-ds.xml file in JBOSS_HOME/server/default/deploy with the following text:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>jdbc/wso2wsas_db</jndi-name>
<connection-url>jdbc:derby:../database/WSO2WSAS_DB/connection-url>
<driver-class>org.apache.derby.jdbc.EmbeddedDriver</driver-class>
<user-name>wso2wsas</user-name>
<password>wso2wsas</password>
</local-tx-datasource>
</datasources>

3. Apache Geronimo AS

Version 1.1.1

1. Creating connectors with Geronimo

The easiest way to manage the Geronimo server is by using the management console. The management console can be accessed from the URL http://localhost:8080/console. The default user name is system, and the password is manager. Web server connectors can be managed by using the "Web Server" link found under the "Console Navigation".

2. Deploying data sources

Data sources can also be easily created with the management console, using the "Data pools" link found under the "Console Navigation". The Deployer tool can also be used to deploy a data source if a deploy plan is present. In this case, use the following command.

java -jar bin/deployer.jar --user system --password manager deploy <path to deploy plan> 
repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar

3. Deploying Web applications

The Deployer tool can be used to deploy web applications. Use the following command.

java -jar bin/deployer.jar --user system --password manager deploy <pathto Web application>

Issues to Note

   <category name="org.hibernate">
      <priority value="ERROR"/>
   </category>

Generic Web Application Server

Installation Instructions

For Web application servers other than JBoss, Apache Tomcat and Geronimo, follow the installation steps as given below.
  1. Unzip wso2wsas-servlet-edition-java-1.1.zip
  2. Run install.sh for Linux or install.bat for MS Windows from wso2wsas-servlet-edition-java-1.1/bin
  3. Select the WSO2WSAS_HOME.
  4. Select the Application Server's WAR file deployment directory.
  5. Configure HTTP, HTTPS and configure the WSO2 WSAS JNDI datasource. See advanced configurations for more details
  6. Restart the application server.
  7. Now the Management Console should be available on https://localhost:9443/wso2wsas if you used the default settings.

Advanced Configuration

1. Register a JNDI datasource with the JNDI name jdbc/wso2wsas_db Use the following details to configure this datasource;
 a. Database Driver : org.apache.derby.jdbc.EmbeddedDriver
 b. Database URL : e.g. jdbc:derby:/wso2wsas/WSO2WSAS_DB
 c. Database Username : wso2wsas
 d. Database Password : wso2wsas
NOTE: You should provide the correct path to the WSO2 WSAS database in the database URL 2. Copy the wso2wsas-servlet-edition-java-1.1/lib/derby-10.1.1.0.jar and the wso2wsas-servlet-edition-java-1.1/lib/log4j-1.2.13.jar to your application server's classpath. 3. Copy the JDK tools.jar (in the case of Windows and Linux JDKs) or classes.jar (in the case of Mac OS X) to your application server's classpath, if they have not been added to the application server's classpath already. 4. Enable SSL on your application layer. If you intend to use the key store file shipped with wso2wsas, you should point your application server to it. The wso2wsas key store file is wso2wsas-servlet-edition-java-1.1/conf/wso2wsas.jks If you intend to use your own key store file, you need to configure the server.xml HTTPS KeyStore Location element.

Post Installation Modifications

This section contains information on modifications that can be carried out after WSO2 WSAS has been successfully installed on your application server.

1. The wso2wsas.properties file

This file is created during installation and may be located at wso2wsas.war/WEB-INF/classes/wso2wsas.properties, in your application server's webapp deployment directory. The wso2wsas.home and other application server specific properties can be changed by modifying this file. You may have to re-archive the wso2wsas.war after modifying this file.

2. Changing the WSO2 WSAS database configurations

  1. In your application server's configuration file, locate the section where the wso2wsas JDBC datasource is registered, and modify the relevant parameters.
  2. Locate wso2wsas.hibernate.cfg.xml in ../WEB-INF/classes and change the "dialect" property, if necessary, to match your RDBMS. e.g. for MySQL, the dialect is org.hibernate.dialect.MySQLDialect

3. Changing HTTP/HTTPS ports

In your application server's configuration file, locate the section where the ports have been registered, and changed it to the appropriate values. If you carried out a Generic installation, in addition to modifying your application server's configuration file, you also have to modify the server.xml file, which can be found at WSO2WSAS_HOME/conf.

Accessing the Management Console

Once WSO2 WSAS 2.1 is successfully installed, in order to access the Management Console, first start the server, then launch a web browser instance and point it to the URL https://localhost:9443/wso2wsas (if you are using the default settings). This will take you to the "Sign In" page of the Management Console seen as below. Note: By default, WSO2 WSAS has two listeners; HTTP and HTTPS. The HTTP listener opens on port 9762, while the HTTPS listener opens on port 9443. The admin functionality is exposed only via HTTPS.



Figure10:mgtconsole



For details on the Management Console see Administrator's Guide