Sakai on Websphere Instructions

Owned by Former user (Deleted)
Last updated: Jun 10, 2010 by Former user (Deleted)Version comment
1 min read

Note: This setup and install guide applies to versions 2.6 and 2.7 of the Sakai CLE.

Environment Setup

Websphere

Sakai Build for Websphere

Deployment and Configuration

Sakai Version Upgrades and Deployment

Troubleshooting Issues

Build Automations

Environment Setup

Websphere

Overview

IBM Websphere Application Server 6.1 is a J2EE 1.4 compliant application server. It supports Java Standard Edition 1.5 (a Sakai requirement), and provides an enterprise-level platform for hosting the Sakai CLE in a secure, scalable, and highly available application server environment.

The Sakai CLE requires IBM Websphere Application Server 6.1.0.17. The installation process starts with the base WAS 6.1 installation, followed by an update to bring the version to 6.1.0.17. The installation instructions and screenshots refer to a Linux environment, although the general steps can be followed for a Windows environment as well.

Requirements

This installation requires the IBM Websphere Application Server 6.1 install package, the 6.1.0.17 fix package, and the IBM Update Installer install package. For additional Websphere Application Server requirements please see the release notes available with each package.

In addition to the recommended settings to run IBM Websphere Application Server 6.1, if on Linux, an increased ulimit size should be set to reduce the possibility of running out of filehandles when deploying and running Sakai on Websphere. Deployment of Sakai on Websphere using DB2 has been known to have particularly high file usage. A ulimit of 4096 is an adequate amount. Please note that if you set the ulimit by running 

ulimit -n <size>

it only affects the current shell.

Installation

Installing WebSphere Application Server





In your terminal, change directory to the WAS installation package directory, and type './WAS/install' to start the installation. The above screen should display. Click the next button.





Accept the License and click Next.





Read and understand the prequisites check. Note any warnings that are displayed and fix them if required. Once ready, click Next.





For a production environment, it's not recommended to install the sample applications. Leave unchecked and click Next.





Enter the path where Websphere should be installed. For eg. '/opt/IBM/WebSphere/AppServer'. Click Next.





Click on the checkbox to enable administrative security (recommended for a production environment). Enter a user name and password to be used whenever accessing the Admin Console. Click Next.





Installation will begin.





Confirm that the installation was a success, then click Finish.


This completes the installation of Websphere Application Server 6.1. The next section details how to upgrade it to the required 6.1.0.17 version.

Updating WebSphere

Although WAS 6.1 is installed, the Sakai CLE requires WAS 6.1.0.17.

To upgrade WAS, the Update Installer must first be installed before the 6.1.0.17 can be applied.

Installing the Update Installer


The Update Installer is a tool that applies updates and fixes to an existing installation. It is required to apply the 6.1.0.17 fix to the WAS 6.1 installation. This section can be skipped if the Update Installer has already been installed.





In your terminal, change directory to the Update Installer installation package directory, and type './install' to start the upgrade process. The above screen should display. Click on Next.





Accept License Agreement and click Next.





Read and understand the prequisites check. Note any warnings that are displayed and fix them if required. Once ready, click Next.





Enter the path where the Update Installer should be installed. For example, '/opt/IBM/Websphere/UpdateInstaller'. Click Next.





Review the summary and if correct, click Next.





The Update Installer will now install.





Confirm that the Update Installer was successfully installed. Then click the Checkbox to launch the IBM Update Installer on exit and click Finish.

Installing the WAS Upgrade






On exit of the Update Installer installation wizard, the IBM Update Installer tool starts. Click Next.





Enter the path of the WAS 6.1 installation you would like to update. This is the same path you entered in Step 5. Click Next.





Click the radio button beside 'Install maintenance package' and click the Next button.





Enter the path to the location of the 6.1.0.17 maintenance fix package. Click the Next button.





Review the summary and if correct, click the Next button.





The WAS 6.1 installation will be updated with the 6.1.0.17 maintenance package.





Confirm the successful update of WAS 6.1 to WAS 6.1.0.17, and click Finish to exit.

Creating a WAS Profile

Websphere places files into one of two separate environments. It installs the core product files (the "system" files) in one location, and in a separate location it creates profiles, which is a run time execution environment that includes configuration files, the default location for deployed applications, logs, and other data. All profiles on a machine can share the same core product files, which they cannot modify.

To create a profile that is to be later used as the run time execution environment for Sakai, navigate to the bin directory of WebSphere's AppServer. For e.g. '/opt/IBM/WebSphere/AppServer/bin'.

In this directory, run the manageprofiles.sh script with the following parameters to create a new profile.

./manageprofiles.sh -create -templatePath /opt/IBM/WebSphere/AppServer/profileTemplates/default 
   -profileName <the name of the profile> -profilePath <the path where the profile should be installed>



For e.g.,

./manageprofiles.sh -create -templatePath /opt/IBM/WebSphere/AppServer/profileTemplates/default 
   -profileName sakaiTest -profilePath /opt/IBM/WebSphere/AppServer/profiles/sakaiTest


Sakai Source Build for Websphere

Websphere is no longer supported. Use at your own risk!

Overview

The build process for the Sakai CLE on Websphere makes use of the existing build procedure and Apache Maven build scripts.

Tailoring the build for Websphere

The additional files under the 'was' directory contain scripts and Websphere specific files that are used to build Sakai for deployment in Websphere. These scripts invoke the Maven build scripts created by the community, but then tailor the build process for a Websphere environment.

The Build Process

The Maven build process for Sakai CLE for Websphere creates an Sakai CLE build in the form of an EAR file that is deployable within Websphere. To achieve this, the build automates and executes the following steps:
• Downloads any dependencies
• Invokes the existing Maven tasks to compile the source code
• Invokes the existing Maven tasks to package the WARs and JARs
• Invokes the existing Maven tasks to deploy the JARs to the directories specified in the settings.xml file
• Packages the EAR using the Maven EAR plugin

Prerequisites

Before starting the build process, a set of perquisites must be met in order to build successfully.

  • Target Environment
    Websphere Application Server (WAS) 6.1.0.17 or higher must be installed in the target environment. In addition, the build is recommended to be executed on the same server as WAS, because it deploys a set of shared libraries and files to a location that Websphere must have read/write access to. During this time, Websphere should be shut down until the build process is complete. If the build is to be performed in a separate environment and then moved to the target environment, an additional step of manually moving the above files must be performed.
  • Sakai Source
    The Sakai source can be obtained from the Sakai Subversion respository (https://source.sakaiproject.org/svn/sakai/trunk).
Maven settings.xml File

A set of properties are required in your M2 settings.xml file:

<appserver.home>=<location of shared library directories>
<maven.tomcat.home>= <same as above>
<sakai.appserver.home> = <same as above>

The above variables should be set to the location where the shared libraries and property files should reside. It can be any directory on the file system that Websphere has read/write access to. If the build is not being performed on the same server as the WAS installation it will be deployed to, then a temporary directory can be used for now. This scenario requires an additional manual step of copying this entire directory structure to the directory that Websphere has read/write access to.

The following are the contents of a sample settings.xml file:

<settings xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>tomcat5x</id> 
      <activation>
        <activeByDefault>true</activeByDefault> 
      </activation>
      <properties>
        <appserver.home>C:/opt/weeklybuild/WASshared</appserver.home> 
        <maven.tomcat.home>C:/opt/weeklybuild/WASshared</maven.tomcat.home> 
        <sakai.appserver.home>C:/opt/weeklybuild/WASshared</sakai.appserver.home> 
        <surefire.reportFormat>plain</surefire.reportFormat>
        <surefire.useFile>false</surefire.useFile>
      </properties>
    </profile>
  </profiles>
</settings>

 

Performing the Build Process

To start the build process, ensure that all prerequisites are met in the previous section.
The was Maven profile will be used to tell Maven this build is for Websphere. Change to the <source> directory, and type

mvn clean install -Pfull,was sakai:deploy

to build the EAR file and deploy the necessary artifacts.

When the process is complete, a successful build will produce the following results:

  • a directory of shared libraries and files will be deployed to the directories specified in the settings.xml file
  • the deployable EAR file will be in the 'was/ear/target' directory

You must then obtain the proper database driver (mysql-connector-java-5.0.5-bin.jar for MySQL) and place it into the common/lib directory.

If the build was performed on a server separate from the target WAS instance, then move or copy the components, shared, server, and common directories from the directory of shared libraries and files to a location that the target WAS instance has read/write access to.

Deployment and Configuration

Overview

Deploying applications on the IBM Websphere Application Server (WAS), a J2EE 1.4 compliant application server, is performed using the Integrated Solutions Console (formerly known as the Websphere Admin Console). This is a web-based application installed by default during the WAS installation. It will follow the step-by-step wizard provided by the console.

The Sakai CLE, in the form of an Enterprise Archive (EAR) file, will be deployed using this Integrated Solutions Console. Additional steps will be required to configure Websphere to properly host Sakai.

Requirements

This installation requires IBM Websphere Application Server 6.1.0.17 or higher and access to its Integrated Solutions Console. Please refer to the Websphere Application Server Install Guide for WAS installation information. It also requires the two resulting artifacts from the build process:

  • a directory of shared libraries and files will be deployed to the directories specified in the settings.xml file
  • the deployable EAR file will be in the 'was/ear/target' directory

If the build took place on a separate server than the one that Websphere Application Server is installed on, then copy the directory of shared libraries and files to a location on the filesystem that is WAS has read/write access to.

Deployment

Startup and Verification

First start up and verify that Websphere has been installed properly by following the next two steps.


In your terminal, browse to the new profile you created and navigate to its firststeps directory. Type './firststeps.sh' to start Deployment. The Above screen should appear. Click 'Start the server' and verify that WAS and the profile created can start successfully.


In the First Steps menu, click on Administrative Console.

Setting up the Shared Library

Websphere must be configured to use Sakai's shared library files found in the common/lib, server/lib, and shared/lib directories.


The Integrated Solutions Console should appear. Make a note of the URL. Enter the username and password if required (determined during the WAS installation process) and click the 'Log in' button to enter.


Click on Environment -> Shared Libraries. Set the scope to the option which defines both the Node and Server values. Click New.


Enter the name of the new Shared Library as 'sakaiLib'. Enter the directory paths for the common, server and shared libraries, as determined in Section 3 or during the build process. For eg.

/opt/WASshared/common/lib/
/opt/WASshared/server/lib/
/opt/WASshared/shared/lib/

Make sure each path has a trailing / and click OK and save the changes made.


Click on Application servers -> server1 -> Java and Process Management -> Class Loader and click the New button.


Select 'Classes loaded with application class loader first' and click OK.


Click on the newly defined Class loader and then click the 'Shared library references' link.


Click the New button and select 'sakaiLib' as the Library name. Click OK and save the changes.

Configure Websphere's Java Runtime Environment

Websphere's JRE must be configured properly for Sakai. This includes telling it where the sakai home and components directories are. For the sakai home directory, choose a directory on the filesystem accessible by Websphere with read/write access.


Click on Application servers -> server1 -> Java and Process Management -> Process Definition -> Java Virtual Machine. In the Generic JVM arguments field, set the sakai.home and sakai.components.root system properties to the paths to the sakai home and components folders respectively, using trailing slashes. In addition set the -Djavax.xml.transform.TransformerFactory=org.apache.xalan.xsltc.trax.TransformerFactoryImpl. Finally, set the sakai.demo=true if you want to use the built in sample course management data. For eg:

-Dsakai.home=/opt/WASshared/sakai/ -Dsakai.components.root=/opt/WASshared/components/
-Djavax.xml.transform.TransformerFactory=org.apache.xalan.xsltc.trax.TransformerFactoryImpl -Dsakai.demo=true

In addition, it is highly recommended to set the Initial Heap and Maximum Heap sizes to an appropriate amount for the server. An initial heap size of 1024 is recommended.

Configure Websphere's Session Management

Websphere's session management must be configured to use a different 'cookie' ID than the one Sakai uses. Not following this step can lead to corrupted user sessions which causes the user to automatically logout. Click Servers > Application servers > server_name > Web container settings > Session management > Enable cookies. Change the Cookie Name to something other than "JSESSIONID", for eg. "WASSESSIONID". 

Install the Sakai EAR File

The Sakai EAR file can now be deployed.


Click Applications -> Install New Application and select the Remote file system. Supply the path to the Sakai CLE EAR file created during the build process and then click Next.


Accept the default options by clicking Next.


View the list of WAR modules to be installed and click Next.


Use the default virtual host for the WAR modules by accepting the default and click Next.


Verify and click Finish.


Installation will start. Once complete, click Save. Once the saving process is complete, shutdown Websphere.

Sakai Configuration

Use an existing sakai.properties file or customize the reference version in the source, found in the reference\docs\sakai.properties. This must be copied to the previously selected sakai home directory.

Edit the file and uncomment the 'servlet.container' property, setting it to 'websphere'.

servlet.container=websphere

Restart

Before restarting, if on Linux, ensure that the ulimit for the server is at 4096 or higher. Please note that if you set the ulimit by running 'ulimit -n <size>', it only affects the current shell. See the Requirements section of the Websphere Application Server Install Guide for more information.

Restart Websphere to start the Sakai CLE on WAS.

Sakai Reinstallation or Upgrading

When reinstalling or upgrading to a new version of Sakai on a Websphere server that already has an instance deployed, make sure to do the following:
1) uninstall the existing Sakai EAR file and then stop the Websphere server
2) (optional) remove or rename the directory repository under .m2
3) delete the contents of the shared libraries but making sure to save a copy of the sakai.properties file and any database driver files.
4) perform a maven build as described above (Performing the Build Process)
5) startup Websphere and from the admin console install the new EAR file (Install the Sakai EAR File)
6) restart Websphere

Build Scripts

The Marist/IBM joint study has produced build scripts that can build and deploy Websphere. They can be found here.