WSO2 Web Services Application Server Servlet Edition for Java, v1.1 - Installation Guide

This installation guide provides details about installation of the WSO2 WSAS Servlet Edition for Java. This also includes information on how to configure WSO2 WSAS on JBoss, Geronimo & Tomcat servers. Some guidelines on installing WSO2 WSAS on other application servers has also been included.

Your feedback on WSO2 WSAS for Java is most appreciated. Please send them to our mailing lists.

Content

Introduction

The WSO2 WSAS Servlet Edition should be installed on a J2EE compliant servlet container.

Download WSO2 WSAS Servlet Edition for Java: wso2wsas-servlet-edition-java-1.1.zip

WSO2 WSAS Servlet Edition has been fully tested on the following J2EE Application Servers and specific installation instructions for each these servers are listed under Application Server Specific Installation section.

J2EE Application Servers

Apache Tomcat Server:

JBoss AS:

Apache Geronimo AS:

General:

Web application servers which do not fall under the above list will have to follow the Generic Application Server Installation Steps described below.

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 war distribution

Operating System Tested on Windows XP, Linux, Mac OS X, Fedora core, Ubuntu, Gentoo

Application Server Specific Information

Installation Instructions

Follow the simple installation steps to successfully install WSO2 WSAS into JBoss AS, Apache Geronimo AS or Apache Tomcat server.

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 and its version.

5. After this point there are a few application server specific steps to follow:

Apache Tomcat Server:

JBoss AS:

6. Some specific libraries and application server specific files will be copied to the relevant directories

7. Restart the application server.

8. 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="tungsten"
 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 for Java.

2. Registering the WSO2 WSAS Data Store

To register Tungsten 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 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 using the management console. The management console can be accessed from the url http://localhost:8080/console. Default user name is system and 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 created easily with the management console, using the "Data pools" link found under the "Console Navigation". Deployer tool can also be used to deploy a data source if 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

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 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 servers 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 App server's classpath, if they are not already added to the App server's classpath.

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. wso2wsas.properties file

This file is created during installation and can be located at wso2wsas.war/WEB-INF/classes/wso2wsas.properties, in your application servers 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 these ports have been registered, and changed it to the appropriate values.

If you carried out a Generic installation, in addition to modifying your application servers' 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 1.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: WSO2 WSAS by default 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