WSO2 Tungsten (Embeddable) Installation Guide

Introduction

Web application archive (war) installation is used to install Tungsten server as part of a J2EE compliant servlet container (Web application server).

J2EE Web Application Servers

Apache Tomcat:

System Requirements

Web Application Server Specific Information

Installation Instructions

Follow the simple installation steps to successfully install WSO2 Tungsten as part of a Apache Tomcat or JBoss servlet containers.

1. Unzip tungsten-java-embeddable-1.0.zip

2. Run install.sh for Linux or install.bat for MS Windows from tungsten-java-embeddable-1.0/bin

3. Select the TUNGSTEN_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:

Advanced Configurations

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:

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="tungsten/conf/tungsten.jks" 
   keystorePass="tungsten" />

NOTE: You can use any keystoreFile of your preference instead of the tungsten.jks which is shipped with WSO2-Tungsten.

2. Registering the Tungsten Data Store

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

<Context path="/tungsten" >
  <Resource name="jdbc/tungsten_db"
    auth="Container"
    type="javax.sql.DataSource"
    maxActive="100"
    maxIdle="30"
    maxWait="10000"
    username="tungsten"
    password="tungsten"
    driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
    url="jdbc:derby:../database/TUNGSTEN_DB;create=true"/>
</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="tungsten/conf/tungsten.jks"
keystorePass="tungsten />

NOTE: You can use any keystoreFile of your preference instead of the tungsten.jks which is shipped with WSO2-Tungsten.

2. Registering the Tungsten Data Store

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

<Context path="/tungsten" docBase="tungsten"
 reloadable="true" crossContext="true">
   <Resource name="jdbc/tungsten_db" auth="Container"
    type="javax.sql.DataSource"/>
      <ResourceParams name="jdbc/tungsten_db">
        <parameter><name>username</name><value>tungsten</value></parameter>
        <parameter><name>password</name><value>tungsten</value></parameter>
        <parameter><name>driverClassName</name>
        <value>org.apache.derby.jdbc.EmbeddedDriver</value></parameter>
        <parameter><name>url</name>
        <value>jdbc:derby:../database/TUNGSTEN_DB;create=true</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="tungsten/conf/tungsten.jks"
    keystorePass="tungsten"
    clientAuth="false" protocol="TLS" />
</Connector>

NOTE: You can use any keystoreFile of your preference instead of the tungsten.jks which is shipped with WSO2-Tungsten.

2. Registering the Tungsten Data Store

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

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

Issues to Note

1. 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 tungsten uses the latest hibernate version, which conflicts with the older version used by jboss.
2. 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
3. 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 smooth operation replace the ant.jar with the ant-1.6.x.jar found in the tungsten lib folder. Also the ant-nodeps-x.x.x.jar needs to be copied into the jbossweb-tomcat50.sar.
4. On Jboss version 4.0.0 and possibly other versions, the windows installation may cause problems if the tungsten home resides in a directory path which has spaces.
5. 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 Tungsten.
6. 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 Tungsten.
7. 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>

8. In MacOSX the classes.jar needs to be copied into the commons/lib dir of 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 and Tomcat, follow the installation steps as given below.

1. Unzip tungsten-java-embeddable-1.0.zip

2. Run install.sh for Linux or install.bat for MS Windows from tungsten-java-embeddable-1.0/bin

3. Select the TUNGSTEN_HOME.

4. Select the Application Server's WAR file deployment directory.

Advanced Configuration

1. Register a JNDI datasource with JNDI name jdbc/tungsten_db

Use the following details to configure this datasource;

 a. Database Driver : org.apache.derby.jdbc.EmbeddedDriver
 b. Database URL : e.g. jdbc:derby:/tungsten/TUNGSTEN_DB
 c. Database Username : tungsten
 d. Database Password : tungsten

NOTE: You should provide the correct path to the Tungsten Database in the Database URL

2. Copy the tungsten-java-embeddable-1.0/lib/derby-10.1.1.0.jar and the tungsten-java-embeddable-1.0/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 tungsten, you should point your application server to it. The tungsten key store file is tungsten-java-embeddable-1.0/conf/tungsten.jks

If you intend to use your own key store file, you need to configure the tungsten.xml HTTPS KeyStore Location element.

Post Installation Modifications

This section contains information on modifications that can be done after WSO2-Tungsten has been successfully installed on your application server.

1. tungsten.properties file

This file is created during installation and can be located at tungsten.war/WEB-INF/classes/tungsten.properties, in your application servers webapp deployment directory.

The tungsten.home and other application server specific properties can be changed by modifying this file. You may have to re-archive the tungsten.war after modifying this file.

2. Changing the Tungsten database configurations

1. In your application server's configuration file, locate the section where the tungsten JDBC datasource is registered, and modify the relevant parameters.
2. Locate hibernate.cfg.xml in the tungsten-core-@tungsten_version@.jar 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 tungsten.xml file which can be found at TUNGSTEN_HOME/conf.

Accessing Tungsten Management Console