Section - Sakai Source Websphere Installation (2.5)

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

h1 Sakai CLE Build Overview & Procedures

h2 _1.1. Purpose_
The purpose of this document is to detail the build process of the Sakai CLE for a Websphere environment, creating deployable components from source code. It provides an overview of the tools and scripts to automate the build, and instructions on how to configure and execute the build process.

h2 _2. Overview_
The build process for the Sakai CLE on Websphere makes use of the community edition's build procedure and Apache Maven build scripts. Apache Maven is a software tool for project management of Java-based projects and provides the ability for automated software builds. It is similar in functionality to the Apache Ant tool, but has a simpler build configuration model, based on an XML format. Additional documentation regarding how Maven is used in the Sakai community edition can be found in the document, ~How we build Sakai using Maven~.

This community build process was appended with additional scripts that would build on the existing community build procedures but then tailor the build for a Websphere environment. This additional scripts can be found under the 'was' directory.

h3 _2.1. Tailoring the build for Websphere_
The additional files under the 'was' directory contain scripts and Websphere specific files that are used to build the application to be deployed in Websphere in the form of an EAR (Enterprise Archive) file. These scripts invoke the Maven build scripts created by the community, but then tailor the build process for a Websphere environment.

In addition to these scripts, an 'overlay' directory contains Websphere-specific files that will overwrite existing files that that only work in Tomcat. While it is preferable that there are no application server specific files, or at the very least, this type of choice is determined at runtime via configuration files, there are some cases where Websphere-only files are required at compile time. These are usually application configuration files that must be included as part of a build (e.g. a web.xml file). The downside is that this creates a duplication of files that differ only with slight application server specific variations. Because of this, this overlay directory is used only when there is no other way to include these variations.

h2 _3. 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:
• Performs a prerequisite check to ensure the required environmental variables are define
• Download any dependencies
• Invokes the community Maven scripts to compile the source code
• Invokes the community Maven scripts to package the WARs and JARs
• Invokes the community Maven scripts to deploy the JARs to the directories specified in the build.properties file
• Deletes deployed JARs that conflict with Websphere's default set of JARs
• Packages the EAR using the Maven EAR plugin
• Temporarily unzips the newly created EAR
• Temporarily unzips WAR files from the unzipped EAR and deletes additional conflicting JAR files
• Copies Websphere specific IBM configuration files into the unzipped EAR
• Packages the EAR file once again ready for deployment

h3 _3.1. Prerequisites_
Before starting the build process, a set of perquisites must be met in order to build successfully.
h4 _3.1.1. Target Environment_
Websphere Application Server (WAS) 6.1.0.17 or higher must be installed in the target environment (see the WAS Install Guide document for instructions). 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.

h4 _3.1.2. Sakai Source_
The Sakai source can be obtained from the Sakai Subversion respository (https://source.sakaiproject.org/svn/sakai/trunk). Follow these instructions to obtain the appropriate source code containing the necessary Websphere modifications.
h4 _3.1.3. Marist Customizations (Optional)_
This step is optional and only is performed in order to obtain the Marist UI, CAS/LDAP and other customizations for the application. After checking out the latest source, issue the following commands. Note: because the local source directory will be different from the repository, each command must be run from the correct subdirectory.

In the local source, navigate to the login directory and run
• svn merge -r 3:4 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/login
• svn merge -r 12:13 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/login

Note: You will need to edit the login/login-tool/tool/src/webapp/WEB-INF/web.xml file to have the correct url to redirect logins back to your own server. Currently, CAS will redirect to ilearn.marist.edu. Instead, supply the server name and port number for the param-value. For eg;
~~<param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
<param-value>148.100.51.60:9080</param-value>~~

In the local source, navigate to the portal directory and run
• svn merge -r 6:7 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/portal

In the local source, navigate to the osp directory and run
• svn merge -r 6:8 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/osp
• svn merge -r 13:15 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/osp
• svn merge -r 17:18 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/osp

If the last command did not add three additional files, navigate to osp/portal/webapp/src/webapp/WEB-INF/category/ and manually export each file.
• svn export http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/osp/portal/webapp/src/webapp/WEB-INF/category/myworkspacebuserdstaff.My_Account.xhtml
• svn export http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/osp/portal/webapp/src/webapp/WEB-INF/category/myworkspacebuserdstaff.My_Events.xhtml
• svn export http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/osp/portal/webapp/src/webapp/WEB-INF/category/myworkspacebuserdstaff.My_Tools.xhtml

In the local source, navigate to the reference directory and run
• svn merge -r 8:12 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/reference
• svn merge -r 15:17 http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/reference

If the last set of commands did not add an additional file, navigate to reference/docs/ and manually export the file
• svn export http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/reference/docs/ilearn.local.properties

In the local source, navigate to osp/portal/webapp/src/webapp/WEB-INF/transform/ and manually export the file
• svn export http://b1bc5.is.marist.edu /svn/cle_2-4-1/trunk/osp/portal/webapp/src/webapp/WEB-INF/transform/osp-portal.xsl

In the local source, navigate to osp/portal/webapp/src/java/org/theospi/portfolio/portal/web and issue the command
• svn export http://148.100.51.88/svn/greystone/marist-sakai/marist/osp/portal/webapp/src/java/org/theospi/portfolio/portal/web/XsltPortal.java

In local source, navigate to /was/overlay/reference/library/src/webapp/skin/default/ and issue the command:
• svn export http://148.100.51.88/svn/greystone/marist-sakai/marist/was/overlay/reference/library/src/webapp/skin/default/osp-portal.css

In the local source, navigate to the reference/library/src/webapp/skin directory remove the 'default' directory. Replace it with the Marist UI by issuing the command
• svn export http://b1bc5.is.marist.edu/svn/cle_2-4-1/trunk/reference/library/src/webapp/skin/default

h4 _3.1.4. Java and Maven Requirements_
The Java and Maven requirements detailed in sections 2.1, 2.2, 2.5, and 2.6 of the WAS Install Guide document must be met. These specify the correct Java version, Java environment variable values, the correct Maven version, Maven environment variable values, and the contents of the build.properties file used by Maven.

h4 _3.1.5. Maven build.properties File_
The WAS Install Guide document defines the values required in the build.properties file required to build the Sakai community edition. An additional 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 defined as 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>



h3 _3.2. Performing the Build Process_
To start the build process, ensure that all prerequisites are met in the previous section. Also, note that the following process is still in development and may change once the build process is finalized.

1. 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 shared library location that WAS has read/write access to (or the temporary directory in the scenario where the build is performed on a different server than WAS)
• 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,
• move or copy the entire directory of shared libraries and files to a location that the target WAS instance has read/write access to

This completes the build process. To deploy and install the build onto Websphere, please refer to the Sakai 2.6 CLE Deployment and Configuration on WAS.