10 Minute Guide to Installing WSO2 WSAS on WebLogic

This document by Afkham Azeez is a simple guide to installing WSO2 WSAS Servlet Edition in BEA WebLogic application server. Date: Wed, 7th Mar, 2007 Level: Reads: 9788 Comments: 1 | Login or register to post comments

Afkham Azeez Dir WSO2

Introduction

WSO2 Web Services Application Server (WSAS) is available in two flavors, a stand-alone edition and a servlet-edition. The servlet-edition can be embedded in any J2EE servlet container.

Apache Tomcat, JBoss, and Apache Geronimo:

The installer that is shipped with this edition supports several versions of Apache Tomcat, JBoss, and Apache Geronimo, out of the box, which will get WSO2 WSAS for Java running on these servers with zero manual configuration effort.

Other J2EE Servlet Containers:

For other application servers, a generic installation has to be carried out, and thereafter, the relevant J2EE application server and WSO2 WSAS should be configured manually.

In general, the following steps need to be carried out for an application server such as WebLogic:

1. Run the WSO2 WSAS installer
2. Register a JDBC datasource in your J2EE application server with JNDI name jdbc/wso2wsas_db
3. Enable SSL on the J2EE application server (if it is not already enabled)
4. Configure the host name(listen address) in both WSO2 WSAS & the J2EE application server
5. Configure the HTTP & HTTPS ports in the WSO2 WSAS server.xml configuration file
6. Deploy WSO2 WSAS on the J2EE application server in exploded mode (i.e. not an archive)
7. Restart the J2EE application server, if necessary

In the next few sections, we will look at how the above steps are carried out on the BEA WebLogic AS. We will consider BEA WebLogic version 9.2 during the course of this guide. You will be able to successfully run WSO2 WSAS on your WebLogic server instance if you follow all of these steps in sequence. So grab a cup of coffee, and lets get started with it.

Running the WSO2 WSAS Installer

We will consider an installation on Unix/Linux. (The guidelines for installing on MS-Windows is similar.) Download the WSO2 WSAS for Java, v1.1 servlet edition [1] and extract the archive to a directory, say /temp. Then follow the steps below:

• Run the following installer as the weblogic user

/temp/wso2wsas-1.1/bin/install.sh

• Select the WSO2 WSAS home directory.

The installer will prompt you for the WSO2 WSAS home directory. Say, we selected the default directory suggested by the installer,

/home/weblogic/.wso2wsas.

• Select the J2EE Application Server

The installer will create several directories under the WSO2 WSAS home directory and prompt you for the J2EE application server as follows:

Please select your application server: 
           1. Tomcat Server
           2. JBoss Server
           3. Geronimo Server 
           4. Generic Server 
           : 

Select the Generic Server option (option number 4)

• Specify the WSO2 WSAS deployment directory.

The installer will prompt you for the WSO2 WSAS deployment directory as follows.

Say, this directory is /home/weblogic/.wso2wsas/war

Create this directory if it does not already exist using mkdir /home/weblogic/.wso2wsas/war and provide this directory as the answer to this prompt.

Installing on Generic Server...
  Starting Generic installation...
  Please enter your Application Server's WAR file deployment
  directory : 

Now, the installer will generate the necessary files using the information we provided in the above steps and create the wso2wsas.war archive in the /home/weblogic/.wso2wsas/war directory.

Go to the /home/weblogic/.wso2wsas/ directory and remove the /home/weblogic/.wso2wsas/wso2wsas directory, which is currently created due to a bug in the 1.1 version of the installer.

Rename the /home/weblogic/.wso2wsas/war directory to /home/weblogic/.wso2wsas/wso2wsas. Go to /home/weblogic/.wso2wsas/wso2wsas and extract the wso2wsas.war archive. Remove the wso2wsas.war file.

Next, the log4j.jar needs to be copied to the exploded WAR file's WEB-INF/lib directory. The commands are shown below:

               cd /home/weblogic/.wso2wsas/
               rm -Rf wso2wsas
               mv war wso2wsas
               cd wso2wsas
               unzip wso2wsas.war
               rm wso2wsas.war
               cp /home/weblogic/.wso2wsas/lib/log4j-1.2.13.jar \
               	  /home/weblogic/.wso2wsas/wso2wsas/WEB-INF/lib

In the final command above, please specify the correct Log4J version that shipped with your version of WSO2 WSAS.

WebLogic Configuration

We hope that you have installed BEA WebLogic AS successfully. Let's move on to the next steps.

Creating a WebLogic domain

We will create a fresh WebLogic domain, for completeness sake, but if you have already created a domain, you can skip this section. Assume that the BEA_HOME is /opt/bea. Start the WebLogic config, as the weblogic user, as follows:

/opt/bea/weblogic92/common/bin/config.sh

• In the Welcome dialog box, select the "Create a new WebLogic Domain" option.
• In the "Select Domain Source" dialog box, leave the default values and click Next.
• In the "Configure Administrator Username & Password dialog box" specify the username as "admin" and the password as "admin123"
• In the "Configure Server Start Mode & JDK" dialog box, select "Startup Mode" as the development mode and "Sun JDK" as the JDK.
• In the "Customize Environment & Services Settings" simply select "No" and click Next. We will look at the customizations later.
• In the "Create WebLogic Domain" dialog box, specify the domain name as "wso2wsas" and leave the default domain location, and click "Create".
• Once the domain is successfully created, click "Done". The domain directory should be created at /opt/bea/user_projects/domains/wso2wsas/

Congratulations! You have successfully created a WebLogic domain and can proceed to the next step.

Defining the JDBC Datasource

WSO2 WSAS uses an embedded Apache Derby database instance. In this section, we will see how to register an Apache Derby Embedded JDBC datasource in WebLogic. You are free to choose any other RDBMS. If you wish to use a different RDBMS see [2].

We first need to add the library containing the Embedded Derby driver to the classpath of WebLogic. Copy the derby-10.1.1.0.jar included with the WSO2 WSAS distribution to $BEA_HOME/weblogic92/server/lib/ or any other directory. In our example, the BEA_HOME is /opt/bea.

Edit the /opt/bea/user_projects/domains/wso2wsas/bin/startWebLogic.sh file and add the following line to this file in the appropriate location:

CLASSPATH="${CLASSPATH}${CLASSPATHSEP}/opt/bea/weblogic92/server/lib/derby-10.1.1.0.jar"
  

Start WebLogic as follows:

/opt/bea/user_projects/domains/wso2wsas/bin/startWebLogic.sh

Once it successfully starts, go to the following URL, http://localhost:7001/console, and login as admin/admin123.

Locate the wso2wsas-->Services-->JDBC-->Data Sources menu, click "Lock & Edit" and start creating a new datasource. Enter the following values.

                            Name = jdbc/wso2wsas_db
                            JNDI Name = jdbc/wso2wsas_db
                            Database Type = Derby
                            Database Driver = Other
                          

Click Next. In the "Transaction Option" section, leave the default values and click Next. In the "Connection Properties" section, enter the following values.

                            Database Name = wso2wsas_db
                            Host Name = localhost
                            Port = 1234
                            Database User Name = wso2wsas
                            Password = wso2wsas
                            Confirm Password = wso2wsas
                          

Click Next. In the "Test Database Connection" section, enter the following values.

     Driver Class Name =  org.apache.derby.jdbc.EmbeddedDriver
     URL = jdbc:derby:/home/weblogic/.wso2wsas/database/WSO2WSAS_DB;create=true
     Properties =  user=wso2wsas
                   databaseName=WSO2WSAS_DB;create=true
                   serverName=localhost
                          

Leave the rest of the fields as they are and click Next. In the next screen, select the target and click Finish. Finally select "Activate Changes" on the upper left corner. There should be no errors, and the JDBC Datasource service should start successfully.

Enabling SSL

If you have not already enabled SSL on your WebLogic instance, follow this section.

Locate the wos2wsas-->Environment-->Servers menu, and click "Admin Server". Click the Keystores tab and enter the following values.

        Keystore = Custom Identity & Custom Trust

        Custom Identity Keystore = /home/weblogic/.wso2wsas/conf/wso2wsas.jks
        Custom Identity Keystore Type = JKS
        Custom Identity Keystore Passphrase = wso2wsas
        Confirm Custom Identity Keystore Passphrase = wso2wsas

        Custom Trust Keystore = /home/weblogic/.wso2wsas/conf/wso2wsas.jks
        Custom Trust Keystore Type = JKS
        Custom Trust Keystore Passphrase = wso2wsas
        Confirm Custom Trust Keystore Passphrase = wso2wsas
                          

Now you have successfully added the WSO2 WSAS keystore. Next click on the "SSL" tab and enter the following values.

               Private Key Alias = wso2wsas
               Private Key Passphrase = wso2wsas
               Confirm Private Key Passphrase = wso2wsas
                          

Click "Save", and then click "Activate Changes". Click the "General" tab and verify that SSL has been enabled. You can change the SSL port if you wish.

Setting the Listen Address

It is also better to set the listen address of your WebLogic server instance to an IP other than localhost (if you have an IP address other than localhost.) In general, it is better to set this to your machine's name. This is because when there are several IP addresses (other than localhost), WSO2 WSAS picks the first one.

Locate the wos2wsas-->Environment-->Servers menu, and click "Admin Server". Click the General tab and enter the Listen Address as your machine name, and activate the changes. Next you will have to restart your WebLogic server instance.

If you specified the Listen Address as your machine's name, you will also need to uncomment the following XML element in the /home/weblogic/.wso2wsas/conf/server.xml, and specify the HostName

                            <HostName>thinky</HostName>
                          

My machine's name is thinky, so I specified the "Listen Address" as thinky in the WebLogic configuration above and in the WSO2 WSAS server.xml's HostName configuration.

Security Provider Configuration

Edit the /opt/bea/user_projects/domains/wso2wsas/bin/startWebLogic.sh file and add the following line to this file in the appropriate location:

CLASSPATH="${CLASSPATH}${CLASSPATHSEP}/home/weblogic/.wso2wsas/lib/bcprov-jdk15-132.jar"
                          

If the bcprov-jdk15-132.jar library is not available in the WSO2 WSAS distribution you downloaded, you can download the bcprov-jdk15-135.jar, and change the above CLASSPATH entry correspondingly.

Locate the java.security file in your WebLogic JRE. In this example, we've used the Sun JDK. The java.security file is located at /opt/bea/jdk150_06/jre/lib/security

Add the following line to that file.

security.provider.7=org.bouncycastle.jce.provider.BouncyCastleProvider
                          

Note that security.provider.# will depend on your configuration. Use the appropriate number. For further details see [3]

Yippee! All the hard work is done. We're done with configuring WebLogic, just hang on for a few more seconds, we are almost there.

WSO2 WSAS Configuration

HTTP and HTTPS Ports

In the /home/weblogic/.wso2wsas/conf/server.xml, add the following XML elements;

                            <HTTP>
                                    <Port>7001</Port>
                            </HTTP>

                            <HTTPS>
                                    <Port>7002</Port>
                            </HTTPS>
                            

The ports should be the same as those specified in your WebLogic instance.

Deploying WSO2 WSAS on WebLogic

Go to the wso2wsas-->Deployment menu on the WebLogic console follow these steps.

• Click "Lock & Edit".
• Click "Install".
• Specify localhost/home/weblogic/.wso2wsas as the Location and select the option button in front of "wso2wsas".
• In the " Choose targeting style" section select "Install this deployment as an application" and click Next.
• In the "Optional Settings" section leave the default values and click Finish.
• Next, activate the changes.
• Go back to wso2wsas-->Deployments menu.
• Select the wso2wsas deployments and click on Start-->Servicing all requests.
• In the next confirmation screen click Yes.

The End! Congratulations! The WSO2 WSAS Mangement Console should be available at https://<hostname>:<https_port>/wso2wsas. It was a piece of cake, wasn't it?

Summary

In this guide, we looked at all aspects related to installing WSO2 WSAS on BEA WebLogic Application Server version 9.2. This article is a step-by-step guide to installing the WSO2 WSAS servlet edition on WebLogic. Even though we looked at only WebLogic 9.2, the relevant concepts will be the same on other versions too. For any J2EE application server, the installation process can be summarized into the following steps.

1. Run the WSO2 WSAS installer.
2. Register the WSO2 WSAS JDBC datasource in your J2EE application server
3. Enable SSL on the J2EE application server
4. Configure the host name(listen address) in both WSO2 WSAS and the J2EE application server.
5. Configure the HTTP and HTTPS ports in the WSO2 WSAS server.xml configuration file.
6. Deploy WSO2 WSAS on the J2EE application server
7. Restart the J2EE application server, if necessary.

There are subtle configuration differences between different J2EE application servers, but this article should be a very good guideline for installing WSO2 WSAS on any J2EE application server.

More Information

WSO2 WSAS How To Series

Bibliography

[1] Download WSO2 WSAS servlet edition- http://dist.wso2.org/products/wsas/wso2wsas-servlet-edition-java-1.1.zip

[2] Changing the WSO2 WSAS RDBMS- http://www.wso2.org/library/150

[3] Specifying a new security provider- http://ws.apache.org/axis2/faq.html#a3

[4] For installing on other application servers - http://wso2.org/project/wsas/java/1.1/docs/installationguide.html

[5] Documentation index for WSO2 WSAS for Java v 1.1 - http://wso2.org/project/wsas/java/1.1/docs/index_docs.html

[6] Home page for WSO2 WSAS for Java - http://wso2.org/projects/wsas/java