[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.2.1 in the Standalone Mode

Installing on Microsoft Windows

Note: The WSO2 WSAS, v2.2.1 release has been successfully tested only on Windows XP.

You can use the install.bat file in the WSAS distribution to install WSAS as a Windows NT service. This installation script is available at WSO2WSAS_HOME/bin.

Here are the steps:

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.



Network service

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.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.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.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.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.2.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.

Remove Installation

On MS Windows systems, to remove the WSAS Windows NT service;

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

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

Accessing the Management Console

Once WSO2 WSAS , v2.2.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.



mgtconsole

For details on WSO2 WSAS Management Console see the User Guide

Installing WSO2 Web Services Application Server, v2.2.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.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

  • On JBoss version 4.0.0 and possibly some other versions, the hibernate2.jar and cglib-full-2.0.1.jar should be removed from the lib directories since wso2wsas uses the latest hibernate version, which conflicts with the older version used by JBoss.
  • On JBoss version 4.0.0 and possibly some other versions, if the jboss-ws4ee.sar is present inside the deploy directory, the admin service will not start due to a conflict in the WSDL API. In this case, the jboss-ws4ee.sar needs to be completely removed from the deploy directory
  • On JBoss version 4.0.0 and possibly other versions, the ant.jar file included inside the jbossweb-tomcat50.sar may cause problems with the code generation. In order to ensure a smooth operation, replace the ant.jar with the ant-1.6.x.jar found in the wso2wsas lib folder. Also the ant-nodeps-x.x.x.jar needs to be copied into the jbossweb-tomcat50.sar.
  • On JBoss version 4.0.0 and possibly other versions, the Windows installation may cause problems if the wso2wsas home resides in a directory path which has spaces.
  • On JBoss version 4.0.1 JBOSS_HOME/server/default/deploy/jboss-hibernate.deployer should be removed since some of its hibernate related libraries conflict with the latest hibernate libraries used by WSO2 WSAS.
  • On JBoss version 3.2.7 JBOSS_HOME/server/default/deploy/jboss-hibernate.sar should be removed since some of its hibernate related libraries conflict with the latest hibernate libraries used by WSO2 WSAS.
  • The output from Hibernate is extremely verbose. Add the following segment to your log4j.xml to avoid this output:
   <category name="org.hibernate">
      <priority value="ERROR"/>
   </category>
  • In MacOSX the classes.jar needs to be copied into the commons/lib dir of the Tomcat installation in order to run the generate client and 'Try it!' features.

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.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 User Guide