Content

1.0 Introduction

2.0 Populating the media tree

2.1 Downloading the files for WebSphere Application Server

2.2 Downloading the files for WebSphere Portal
2.3 Downloading and installing the database files
2.4 Downloading and installing the Installation Manager files

3.0 Preparing for the installation

3.1 Installing the database client on the Portal nodes

3.2 Creating the environment tree and generating the automation project by running the Environment Generation wizard
3.3 Updating the configuration file
3.4 Modifying the Rational Automation Framework configuration

4.0 Running and debugging the project

4.1 Estimating the time needed for the installation

4.2 Connecting to the Portal Server after the project completes

5.0 Troubleshooting

5.1 Recovering from common failures

6.0 References

---

1.0 Introduction

This white paper is designed to help WebSphere Portal Administrators roll out a new WebSphere Portal Network Deployment 8.0 (ND) environment as a non-root user by using the Rational Automation Framework Environment Generation wizard. Administrators should review this document before installing a new WebSphere Portal 8.0 ND environment. The following pages provide an in-depth look at a successful WebSphere Portal 8.0 ND environment installation. In addition, extensive troubleshooting material is also provided.

Due to a known defect under WebSphere Portal 8.0, the Rational Automation Framework configuration will need to be modified to allow Portal 8.0 to be install with Portal 8.0 Fixpack 1.

PM64484: com.ibm.websphere.portal.replace.inventory_8.0.0.20120421 fails to delete for non-administrative install user
http://www-01.ibm.com/support/docview.wss?uid=swg1PM64484

After you complete the steps in this white paper, you should have a WebSphere Portal 8.0 ND cell that contains two WebSphere Portal nodes in a single cluster, with Web Content Manager (WCM) enabled. The environment described is a five-computer setup:
· A 64-bit Red Hat Linux server with Rational Automation Framework installed.
· A server with NFS installed, containing the media tree. Placing the media tree on a separate server is optional.
· A 64-bit Cent OS Linux server that has DB2 9.7 Enterprise Server Edition installed. The database server hosts the databases for the automation engine and for WebSphere Portal.
· A 32–bit Cent OS Linux server for the first WebSphere Portal node.
· A 64-bit Red Hat Linux server for the second WebSphere Portal node.

2.0 Populating the media tree

Before populating the media tree, the latest version of Rational Automation Framework (3.0.1.2 at this writing) must be installed and configured. Rational Automation Framework 3.0.1.2 performs all the actions specified in this white paper. You can download and install Rational Automation Framework 3.0.1.2 from Passport Advantage.

To install WebSphere Portal, you need the following software.

· A database server
· A database client on each Portal node
· IBM WebSphere Application Server
· IBM WebSphere Portal
· IBM Update Installer
· Fix packs for WebSphere Application Server and WebSphere Portal

To determine which fix packs you must download for the separate components, review the following technote, which describes the software requirements for the different versions of WebSphere Portal.

http://www.ibm.com/support/docview.wss?&uid=swg27007791

This paper describes the steps required to install WebSphere Application Server 8.0 with fix pack 5. After completing these steps, install WebSphere Portal 8.0.0.1 and use DB2 9.7 Enterprise Server and the DB2 9.7 Data Client on the WebSphere Portal nodes. The following tables lists the files you must download and their download locations. Unless otherwise noted, if you download an archive file (.zip or .tar extension), you must extract the contents of the archive to the specified locations.

2.1 Downloading the files for WebSphere Application Server

2.2 Downloading the files for WebSphere Portal

2.3 Downloading and installing the database files

2.4 Downloading and installing the Installation manager files

*The following URLs correspond to the download sites listed above:
· Passport Advantage - http://www.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm
· IBM Fix Central - http://www.ibm.com/support/entry/portal/Downloads

** The WebSphere Portal installers and fix packs are not architecture-specific. In this example, you download only the x86 packages and copy the same installers to both the X32 and X64 directory in the media tree, so that the installers are available to both WebSphere Portal nodes.

3.0 Preparing for the installation

Note the following points about the way Rational Automation Framework installs WebSphere Portal:
· When you typically download the installation archive files from Passport Advantage and install WebSphere Portal from those files, the installer for WebSphere Portal uses the WebSphere Application Server version that was provided as part of the WebSphere Portal installation files. This installation procedure is different from installing WebSphere Portal by using Rational Automation Framework, where Rational Automation Framework first installs the WebSphere Application Server version specified in the Environment Generation wizard, including the latest known fix pack.
· Rational Automation Framework installs WebSphere Portal into the version of WebSphere Application Server that you just installed. When you download the installers to populate the media tree, ensure that you have the right version of WebSphere Application Server downloaded and in the media tree.

To make each computer more identifiable, the following hostnames are used for each of the five servers:

ibm-db2.ibm.com - DB2 database server (contains WebSphere Portal and automation databases)
ibm-wp1.ibm.com - WebSphere Portal Node 01 server and Deployment Manager
ibm-wp2.ibm.com - WebSphere Portal Node 02 server
ibm-raf.ibm.com - Rational Automation Framework server
ibm-media.ibm.com - NFS server that currently hosts the shared media tree

To prepare for the installation, complete the steps in the following sections.

3.1 Installing the database client on the Portal nodes

1. Install the IBM Data Server Client version 9.7 on each of the WebSphere Portal nodes (ibm-wp1.ibm.com and ibm-wp2.ibm.com). Data Server Client is included as part of the Enterprise Server installation package, or available as a download from Fix Central (client portion only). This client is needed so that each of the WebSphere Portal nodes can communicate with the portal databases that are on ibm-db2.ibm.com. If you perform a custom installation for the DB2 Data Server Client, you can choose which features to install. To include all the necessary libraries for the runtime, make sure that the Application development tools > Base application development tools feature is selected. Also make sure that you create a DB2 instance when installing the runtime client. Creating a DB2 instance is essential to the ability of the WebSphere Portal node to communicate with the DB2 server.

2. Verify that the media tree is mounted on the two WebSphere Portal nodes, in the same location on each node. Verify that the media tree is readable and writeable by the user who mounted it on the WebSphere Portal nodes.

3. On the framework server (ibm-raf.ibm.com), verify that the RAFW_HOME/configure.properties file contains the information that the installation actions require. Override the default media home on the target servers by setting the OS_MEDIA_ROOT property. For the example in this paper, set LINUX_MEDIA_ROOT to the path where the shared media tree is mounted on the target systems.

4. If the two WebSphere Portal nodes are new servers where you have not previously run Rational Automation Framework actions, ensure that the remote RAFW_HOME directory (by default /opt/RAFW or C:/RAFW on the target systems) is writeable by the user who will install WebSphere Portal. The automation project that is generated by the Environment Generation wizard requires this write access. To avoid permission issues, this example uses root as the OS user to connect to the WebSphere Portal node. If you plan on using a non-root user, that user must be the owner of the remote RAFW_HOME directory.

5. Create the databases for the WebSphere Portal installation. This example uses the DB2 instance owner user on the Linux DB2 server for all databases. For more information about creating the users and databases for the WebSphere Portal installation, see the documentation at the following location:

http://www-10.lotus.com/ldd/portalwiki.nsf/xpDocViewer.xsp?lookupName=IBM+WebSphere+Portal+8+Product+Documentation#action=openDocument&res_title=Linux_clustered_server_Creating_a_remote_or_local_DB2_database_manually_wp8&content=pdcontent

The following subsections address the creation of the remote database on your specific platform.

Product Documentation
IBM WebSphere Portal 8 Product Documentation
Installing > Installing on Linux
Setting up a cluster on Linux
Preparing the primary node on Linux
Linux clustered server: Configuring your portal to use a database
Linux clustered server: Setting up a remote DB2 database
Linux clustered server: Creating DB2 databases
Linux clustered server: Creating a remote or local DB2 database manually

The example in this paper follows the directions in the “Creating a remote or local DB2 database manually” section for Linux, resulting in six databases. The instance owner (db2inst1) is used to create the different databases.

Checkpoint
In this section you completed the following tasks:
· Verified the WebSphere Portal node access to the shared media tree
· Created databases on the DB2 server

You can now run the Environment Generation wizard to create a new WebSphere Portal cell.

3.2 Creating the environment tree and generating the automation project by running the Environment Generation wizard

1. Log in to the Rational Automation Framework web client and click the Env Gen tab.

2. Click Create a New WebSphere Cell.

3. Use the following tables to complete the fields in the wizard. If you do not see any of these prompts in the wizard, press the Tab key or click another field to refresh the screen. Some fields depend on previous entries; for example WebSphere Portal version is available only after you select WebSphere Portal as the Cell type.

On the General questions page, enter the following values:


Click Next.

On the Deployment Manager questions page, enter the following values:


On the Define nodes page, enter the following values:

Click Next.

On the Define clusters page, enter the following values:


Click Next.

The Environment Generation wizard project runs and generates the user environment tree and the automation project for the new cell. Click Update progress output until the Previous and Return to Main Menu buttons are displayed at the bottom of the page. The last line of the wizard output should be “Environment Generation is Complete,” indicating that the wizard completed successfully.

To return to the web client, click the Console tab. On the left side of the screen, Click Projects. The project that the Environment Generation wizard created, RAFW_WPnd80lnx_wp80, is displayed in the upper right pane. The following naming convention is used: RAFW_environment-name_cell-name. Double-click the project name to see the steps it runs to install and configure WebSphere Portal on both nodes.

3.3 Updating the configuration file

Before you run this project, modify the config_wp_db.properties file so that the installation scripts can locate and configure the database for the WebSphere Portal nodes. Each WebSphere Portal node has its own copy of the config_wp_db.properties file. The majority of the information in each file is the same. The only thing that might change is the path for the DB2 client and Derby client.

1. Edit the config_wp_db.properties file for the primary node. In this example, the file is in the following location: /opt/IBM/RAFServer/user/environments/WPnd61lnx/cells/wp61/nodes/
node01/config_wp_db.properties

2. Note the structure of the file.
· The file contains two sets of properties for each database. Property names of the form source.db-name.property-name refer to the provided Derby database and you do not have to change the values of these properties.
· Property names of the form db-name.property-name refer to the target databases that you just created for this WebSphere Portal installation. The next step addresses changing the values of these properties.

3. Use the following tables to change the values in the file. Note the following details:

· Any properties not explicitly noted in the tables retain their default values.
· The example uses Type 4 drivers to connect to the database, so you do not enter values for the Type 2 properties.
· The value of the dbname.DbHome property value can be any directory on the file system that the DBA.DbUser has permission to write to. This example uses an existing directory where the DB2 server stores database files.
· Verify the correctness of the hostname, port number, and database name in the dbname.DbUrl connect string. In this example, the databases are all located on the same host and instance, so only the database name changes.
· When updating the db2.DbLibrary value near the end of the file, remember that you might also need to update the file name separator for DB2. The separator must be a colon (:) for Linux and UNIX.
· Be mindful of white spaces when entering information into this file. Trailing white spaces can cause the installation to fail.


Feedback Database
Likeminds Database
Release Database
Community Database
Customization Database
Jcr Database
Non-database specific properties
4. After modifying the config_wp_db.properties file for the primary node, copy it over the file that currently exists on the secondary WebSphere Portal node, in our case NODE02.

5. From the /opt/IBM/RAFServer/user/environments/WPnd80lnx/cells/wp80/
nodes/node01 directory, run the following command:

cp config_wp_db.properties ../node02

6. Open the /opt/IBM/RAFServer/user/environments/WPnd80lnx/cells/wp80/
nodes/node02/config_wp_db.properties file. If the paths are different on the different nodes, change the db2.DbLibrary and derby.DbLibrary properties.

3.4 Modifying the Rational Automation Framework configuration

As noted before, Portal 8.0 defect PM64484 prevents a non-root user installation from completing. Since the Rational Automation Framework is configured to install a products base version first followed by any available patches, the defect would be encountered under any and all non-root installation. To avoid this, there are a few items that will need to be manually modified to allow Rational Automation Framework to install Portal 8.0 with Fixpack 1 under a single installation attempt.

1. Update the Rational Automation Framework Portal 8.0 template response file.

The response template is under $RAFW_HOME/product/templates/install/wp/80/wp80_install_response.template.
Where $RAFW_HOME is the location where the Rational Automation Framework rafw directory is located.
By default, this would be under /opt/IBM/RAFServer/rafw.

You will want to modify the following to add the Portal 8.0 Fixpack 1 repository and the appropriate version for Portal 8.0.0.1.

Before:
<repository location='@WP_PATCH_FILES@/repository.config'/> -->

After:
<repository location='@WP_PATCH_FILES@/repository.config'/> -->
<repository location='@WP_PATCH_FILES@/../../patches/fixpacks/wp80_fp1/repository.config'/>


Before:

<offering id='com.ibm.websphere.PORTAL.SERVER.v80' version='8.0.0.20120421_0828' profile='IBM WebSphere Portal Server V8' features='@PRODUCT_FEATURE_NAMES@' installFixes='none'/>

After:

<offering id='com.ibm.websphere.PORTAL.SERVER.v80' version='8.0.1.20130123_1736' profile='IBM WebSphere Portal Server V8' features='@PRODUCT_FEATURE_NAMES@' installFixes='none'/>

2. Update configure.properties file with correct patches list and BASE_STARTING_POINT under each node.


3. Update the Rational Automation Framework build step executing the Portal install to run action without patches.

Since we are installing Portal 8.0 with Fixpack 1 at the same time, we will not need to use the defaults Rational Automation Framework action to install Portal with patches.
To do this, you will need to access the build step under the lagecy Build Forge UI and update the step "Install WP Nodes" under library "RAFW_WP_61_Install_Helper_Library"

Simple Method:
*Can be used for testing or environments where RAF will be used to install only Portal 8.0.

- Update the step "Install WP Node" command to run the action wp_80_install_wp instead of wp_80_install_with_all_patches.

Before:
${RAFW_HOME}/bin/rafw${SCRIPT_EXT} -env ${ENVIRONMENT} -cell ${CELL_NAME} -node ${NODE_NAME} -execute wp_${WP_VERSION}_install_with_all_patches ${MEDIA_TRANSFER}

After:
${RAFW_HOME}/bin/rafw${SCRIPT_EXT} -env ${ENVIRONMENT} -cell ${CELL_NAME} -node ${NODE_NAME} -execute wp_${WP_VERSION}_install_wp ${MEDIA_TRANSFER}


Advance:
This will require creating a new library copied from the RAFW_WP_61_Install_Helper_Library library that will be used under the RAFW_WP_80_ND_Install_Helper_Library for Portal 8.0 installation only.

- Under the RAF legacy Build Forge console UI, find and copy the RAFW_WP_61_Install_Helper_Library library under the Libraries page.

- Rename the "RAFW_WP_61_Install_Helper_Library Copy" library to "RAFW_WP_80_Install_Helper_Library" library.


- Access the build steps for the "RAFW_WP_80_Install_Helper_Library" library.

- Under the "RAFW_WP_80_Install_Helper_Library" steps Update the step "Install WP Node" command to run the action wp_80_install_wp instead of wp_80_install_with_all_patches.

Before:
${RAFW_HOME}/bin/rafw${SCRIPT_EXT} -env ${ENVIRONMENT} -cell ${CELL_NAME} -node ${NODE_NAME} -execute wp_${WP_VERSION}_install_with_all_patches ${MEDIA_TRANSFER}

After:
${RAFW_HOME}/bin/rafw${SCRIPT_EXT} -env ${ENVIRONMENT} -cell ${CELL_NAME} -node ${NODE_NAME} -execute wp_${WP_VERSION}_install_wp ${MEDIA_TRANSFER}

- Finally, update the RAFW_WP_80_ND_Install_Helper_Library library step "Install WP" to inline the RAFW_WP_80_Install_Helper_Library" library.


4. Update the file configure_wp80_base.xml to correct the following Rational Automation Framework defect PI24582.

Due to Rational Automation Framework defect PI24582, you will need to manually update the following file to ensure the process to transfer the database under the Portal 8.0 installation does not encounter the known error.

$RAFW_HOME/product/actions/configure/wp/80/base/configure_wp80_base.xml

208 <trycatch property="failure">
209 <try>
210 <copy_file_from_primary_node file="${file}"
211 tofile="${toFile}"
212 prefix="source.node" />
213 <catch>
214 <rafwfail id="CRWWP1001E" resourcebundle="wp">
215 <logarg value="${failure}" />
216 </rafwfail>
217 </catch>
218 </try>
219 </trycatch>

After:

208 <trycatch property="failure">
209 <try>
210 <copy_file_from_primary_node file="${file}"
211 tofile="${toFile}"
212 prefix="source.node" />
213 </try>
214 <catch>
215 <rafwfail id="CRWWP1001E" resourcebundle="wp">
216 <logarg value="${failure}" />
217 </rafwfail>
218 </catch>
219 </trycatch>


You are now ready to run the automation project to install WebSphere Portal.

4.0 Running and debugging the project

Return to the web client to run the RAFW_WPnd80lnx_wp80project.

1. To run the project, use either of these two methods:
· On the Projects page, click the blue quick-start button
· To review the environment variables and steps that this project runs, click the project name and then click Start Project. If you need to transfer the media to the target system, make sure that the MEDIA_TRANSFER option is set to Transfer Media. After reviewing the steps and variables, click Execute to run the job.

2. On the left menu, click Jobs and click the job name associated with this project execution.

4.1 Estimating the time needed for the installation

A successful run from beginning to end with no failures took 6 hours and 45 minutes in the test environment for this white paper. The following table gives the run times for the longest steps in the project. Remember that these numbers can vary greatly depending on your environment and should be used only as a rough estimate.

4.2 Connecting to the Portal Server after the project completes

To access the WebSphere Portal login screen, navigate to the following URL and log in using the WP_USER and WP_PASSWORD defined in the configuration.properties file in the Rational Automation Framework environment definition for your portal cell:

hostname:10039/wps/portal

If you cannot reach the login screen at that URL, it is possible that portal was configured to use a port other than the default port of 10039. To determine the correct port number, log in to the deployment manager and navigate to the following location:

Servers > ServerTypes > WebSphere application servers

Click the name of one of the servers in the portal cluster (such as wpclone1). In the configuration settings page for the application server, expand Communications > Ports. The correct port number is associated with WC_defaulthost.

If the web page still does not open, more debugging in required. If the installation and configuration steps in the automation project completed successfully, then the most likely source of the error is one of the following places:
· The application servers (application servers not started)
· The deployed applications (applications not started or started with errors)
· The database server (database server is down, instance is down, and so on)

To troubleshoot, look for errors logged in the WebSphere Application Server application server logs for the application servers belonging to the portal nodes.

5.0 Downloading the files for WebSphere Application Server

One common source of problems is typos or white space in the properties files. In case of portal install errors, check these files.

The following failure scenarios were observed during the creation of this white paper. Some of these scenarios require a restart of the project and a reinstallation of the WebSphere products. In these cases, the currently installed products must be stopped before you start the project again. Stopping the products ensures that the products are properly uninstalled before the project attempts to install them again.

If you got partway through installing the product, restarted the job to continue from where it stopped, and encountered another failure, uninstall and then reinstall the products and run the configuration steps again. Typically, if the portal node configuration step fails more than once on the same node, the node is corrupt and the installation should be started again from the beginning, which means uninstalling and then reinstalling. A clean uninstall on UNIX systems means that all processes belonging to the WebSphere products on all nodes are stopped and the product directory is completely deleted.

5.1 Recovering from common failures

The following failure scenarios were observed during testing:

Failure scenario #1: The job failed in the first few minutes while installing WebSphere Application Server on the nodes. On node01, the media tree was not available in the default location, so a symbolic link was created to resolve the issue. On the secondary node, the WebSphere Application Server installation tree was corrupt. The media was downloaded again and expanded into the media tree for that platform and architecture.

Because the job failed early in the cycle, it was restarted by clicking the “Restart Job” button on the failed job page and letting it run through all the steps over again, including the uninstall steps, to clean up any previously installed files. If you uninstall or reinstall WebSphere Application Server and WebSphere Portal repeatedly by using the automation projects, you might notice that the uninstall steps in the project do not always stop the servers properly or remove all the installation files. To avoid this potential problem, complete the following steps:
1. Pause the job after the uninstallation steps.
2. Check the target nodes to ensure that everything was deleted.
3. Resume the job to complete the installation.


Failure scenario #2: WebSphere Application Server and WebSphere Portal were installed on the system, but the project failed on the “Create WebSphere Portal Users and Groups in DMGR File Registry” step when the Rational Automation Framework action attempted to communicate with the Deployment Manager on the default port 8879. Because no starting ports were specified for the WebSphere Application Server installation, and WebSphere Application Server was already installed on the primary WebSphere Portal node, the WebSphere Application Server installer picked the next available ports automatically. Therefore, the SOAP port for this installation ended up being 8881 instead of the default 8879.

If the WebSphere Application Server installation that listens at port 8879 had been running, the action would have tried to create the WebSphere Portal users in the wrong cell. The user creation did not occur because the other WebSphere Application Server installations were disabled at the time. The solution was to change the SOAP port in the cell scope configure.properties file and restart the automation project from the point where it failed.

When you restart a failed job by clicking the Restart Job button in the job log page, make sure that all uninstall and stop steps that failed but continued are cleared. When you restart a failed installation by this method, the uninstall steps are selected as they are assumed to have failed in the previous run, where there was nothing to uninstall, so the automation engine attempts to re-run them. If these steps are not cleared, the project might uninstall WebSphere Portal or WebSphere Application Server or shut down one or more servers when you restart the job.


Failure scenario #3: An error occurred in setting up the primary cluster member action. This was due to a typographical error in the name of the community database in the config_wp_db.properties file, where the name was listed as “commun”. The database creation script actually created a database named “common”. The config_wp_db.properties file was updated with the correct name, and the job was restarted with the following procedure:
1. Click Restart Job.
2. Clear all the steps before the Set up WebSphere Portal cluster member step.

If the Set up WebSphere Portal cluster member step fails during database creation, you can restart the job at that step. The configuration scripts drop any data in the databases and recreate the entries.


Failure scenario #4: An error occurred while configuring Web Content Manager at the point of “Connecting to URL localhost:10039/wps/config/". The error was “[xmlaccess] EJPXB0015E: Server response indicates an error.” The application server logs for the portal node that was being processed showed that the portal applications could not find a DB2 jdbc driver class (ClassNotFound exception). The problem was a typo in the config_wp_db.properties file, which contained a semicolon instead of a colon separating the two DB2 jdbc archive files in the db2.DbLibrary property value. The following steps were taken:
1. The file was corrected.
2. The products were cleanly uninstalled.
3. The project was restarted from the beginning.

6.0 References

· Rational Automation Framework Online Help: https://publib.boulder.ibm.com/infocenter/rafhelp/v3r0m1/index.jsp
· WebSphere Portal Online Help: http://www-10.lotus.com/ldd/portalwiki.nsf/xpDocViewer.xsp?lookupName=IBM+WebSphere+Portal+8+Product+Documentation#action=openDocument&content=catcontent&ct=prodDoc
· WebSphere Portal System Requirements: https://www.ibm.com/support/docview.wss?rs=688&uid=swg27007791
· Passport Advantage - http://www.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm
· IBM Fix Central - http://www.ibm.com/support/entry/portal/Downloads
· Jesse Alva (IBM Rational Automation Framework)