openCRX Installation Guide for WebSphere 6.1

Version 1.10.0

www.opencrx.org

1 About this Book

This book describes the installation of openCRX for IBM WebSphere 6.1.

1.1 Who this book is for

The intended audience are openCRX and application server system administrators.

1.2 What do you need to understand this book

This book describes the installation of openCRX for IBM WebSphere 6.1. The book assumes that you are familiar with IBM WebSphere 6.1 administration and deployment concepts.

1.3 Tips, Warnings, etc.

We make use the following pictograms:

	Information provided as a “Tip” might be helpful for various reasons: time savings, risk reduction, etc. - it goes without saying that we advise to follow our guides meticulously meticulous \muh-TIK-yuh-luhs\, adjective: Extremely or excessively careful about details.
	You should carefully read information marked with “Important”. Ignoring such information is typically not a good idea.
	Warnings should not be ignored (risk of data loss, etc.)

2 Prerequisites

As a first you must download and install the following software:

• Install IBM WebSphere 6.1.

• Download openMDX from here (http://sourceforge.net/project/showfiles.php?group_id=75132).

• Download openCRX from here (http://sourceforge.net/project/showfiles.php?group_id=95219).

IBM WebSphere 6.1 comes with JRE-1.5. However, download the JRE-1.4 version of openCRX and openMDX (e.g. opencrx-1.10.0-core.CRX.jre-1.4.zip).

Before you can install openCRX for WebSphere you must install the database as described in the openCRX database installation guides. If you have successfully installed the openCRX database you are ready to continue with the IBM WebSphere 6.1 setup.

3 Installing openCRX for IBM WebSphere 6.1

After installing IBM WebSphere 6.1 you should be able to start and stop it and launch the Administrative Console as shown below:

Figure 1: IBM WebSphere 6.1 Administrative Console.

The openCRX installation requires the following steps:

• Configure properties for the JVM required by openCRX and openMDX.

• Create and configure the datasource to access the openCRX database.

• Enable security.

• Deploy the openCRX application enterprise archives.

• Start and test openCRX.

4 Installing Libraries

As a first step you must install the openMDX and the database libraries and make them available to WebSphere. You can do this by navigating to Environment > Manage WebSphere Variables.

• openMDX. Add a new variable by clicking new and add the entry with name OPENMDX_HOME and value ${WAS_INSTALL_ROOT}/openmdx/lib as shown below:
  

  Figure 2: Add OPENMDX_HOME as WebSphere variable.

• Database. For most databases there already exist corresponding environment variables. However, the value must be adapted to your environment. E.g. the JDBC driver for PostgreSQL should have the name POSTGRES_JDBC_DRIVER_PATH and – for example – the value ${WAS_INSTALL_ROOT}/postgres as shown below:
  

Figure 3: Add POSTGRESQL_JDBC_DRIVER_PATH as WebSphere variable.

So far you only have created the environment variables. You now must copy the required libraries to the directories that you have configured:

• openMDX – Step 1. Copy the library openmdx-kernel.jar to the directory OPENMDX_HOME, e.g. C:\pgm\WebSphere\AppServer\openmdx\lib. Create the directory if it does not exist.

• openMDX – Step 2. Copy the library openmdx-kernel.jar to the directory WebSphere\AppServer\lib\ext. The library is required by the WebSphere RMIC compiler when you deploy the EARs.

• Database. Copy the library postgresql-8.1-407.jdbc3.jar to the directory POSTGRESQL_JDBC_DRIVER_PATH. Create the directory if it does not exist.

Save the changes you have made so far.

Make sure that you copy the library openmdx-kernel.jar to the directory WebSphere\AppServer\lib\ext. Otherwise the deployment of the openCRX application will fail.

5 Configuring the Java Virtual Machine

Now you must add some options to the JVM configuration. Navigate to Servers > Application Servers > server1 > Process Definition > Java Virtual Machine as shown below:

Figure 4: Configure the Java Virtual Machine.

You must configure the following options:

• Classpath. openmdx-kernel.jar must be added to the classpath. You can use the envrionment variables you have configured in the previous step. Add the entries

• ${OPENMDX_HOME}/openmdx-kernel.jar

• Generic JVM arguments. Add the following options:

• -Dorg.openmdx.compatibility.base.application.j2ee.domain=apps

• -Dorg.openmdx.compatibility.base.application.j2ee.server=server1

• -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol

• -Dorg.openmdx.log.config.filename=C:\pgm\WebSphere\AppServer\server1.log.properties

• Create the file C:\pgm\WebSphere\AppServer\server1.log.properties using a text editor with the following content.

Listing 1: Listing of server.log.properties.

ApplicationId = opencrx-server1
LogFileExtension = log
LogFilePath = C:/pgm/WebSphere/AppServer/logs/
LogLevel = warning
java.LoggingMechanism = SharedDatedFileLoggingMechanism

Adapt C:/pgm/WebSphere/AppServer to your environment!

Save the modifications you have made so far.

Before you continue you must restart (stop and start) WebSphere. The newly configured libraries and environment variables only become active after restarting WebSphere.

Next the Java security policy must be extended. Open the file C:/pgm/WebSphere/AppServer/java/jre/lib/security/java.policy with a text editor and add the lines listed below:

Listing 2: extend the Java security policy.

grant codeBase "file:/C:/pgm/WebSphere/AppServer/openmdx/lib/*" {
permission java.security.AllPermission;
};

This allows the openMDX libraries to access Java system properties.

Alternatively you can disable the Java 2 security in the administration console as shown below:

Figure 5: Disable Java2 security.

6 Configuring the Datasource

openCRX requires the configuration of a JDBC datasource to connect to the openCRX database. You can do this a follows:

Navigate to Resources > JDBC Providers and create a new JDBC provider as shown below:

Figure 6: Create a JDBC provider.

For PostgresSQL fill out the fields as follows:

• Database type: User-defined

• Implementation class name: org.postgresql.jdbc3.Jdbc3ConnectionPool

• Name: PostgreSQL

On the next page you must enter the class path of the JDBC library as shown in Figure 8. For example for PostgreSQL enter ${POSTGRESQL_JDBC_DRIVER_PATH}/postgresql-8.1-407.jdbc3.jar and then click next.

Figure 7: Enter the JDBC driver class path.

Verify whether the values match the environment variables and library names which you have configured in in the previous section. Also verify the values with your JDBC driver documentation. Then click Finish on the summary screen as shown below:

Figure 8: Complete creation of JDBC provider.

Next you must create a datasource. Select Resources > JDBC > Data sources and then select New. Enter the values as shown below:

Figure 9: Configure the datasource.

In Step 1 you must set the values for the following fields:

• Name. CRX.

• JNDI Name. jdbc/opencrx_CRX.

• Component-managed Authentication Alias. Select a principal from the drop down which allows you to login to the database. You can add J2C Authentication Principals under Security > JAAS Configuration > J2C Authentication Data. Make sure that you enter a valid UserId and Password, otherwise WebSphere is not able to establish a connection to the openCRX database and the startup of openCRX will fail.

In Step 2 select the JDBC provider you have created in previously as shown below:

Figure 10: Select JDBC provider.

In Step 3 select the data store helper class name. Do not modify the default value as shown below:

Figure 11: Set data store helper class name.

On the summary page verify the values and then click Finish as shown below:

Figure 12: Finish creation of datasource definition.

Next you must complete the datasource configuration by setting the Additional Properties > Custom Properties as shown below:

Figure 13: Data source custom properties for PostgreSQL.

The properties are driver-specific. The JDBC driver documentation should list the required properties. E.g. PostgreSQL requires the following custom properties:

• databaseName. Set the value to the openCRX database name, e.g. CRX-CRX.

• serverName. localhost.

The datasource configuration is now complete. Save the changes.

7 Configuring Security

openCRX requires that each user is properly authenticated so that sessions can be correlated to user-specific application data and to perform access control. openCRX does not support non-authenticated sessions.

User authentication must be activated in WebSphere as follows:

• Select Security > Secure administration, applications, and infrastructure and check the boxes Enable administrative security and Enable application security as shown in the figure below.

• Set Realm definition to Local Operating System or to another registry listed in the drop down. Local Operating System makes all users and groups defined by the operating systems available as WebSphere users and groups.

• When security is turned on the WebSphere process will run under this operating system user. Typical values are wasadmin, <password>. Under Windows the user must be in the Administrator‘s group.

Figure 14: Enable WebSphere security.

Save the changes you have made so far. Shut down and restart WebSphere.

Security is now turned on and you must supply the login credentials to the startServer command: startServer server1 –username wasadmin –password <wasadmin password>. Otherwise WebSphere will not start.

8 Deploying openCRX

openCRX comes with two enterprise application archives (EAR):

• opencrx-core-CRX-App.ear. Contains the openCRX server components, i.e. Enterprise Java Beans.

• opencrx-core-CRX-Web.ear. Contains the web application for openCRX users.

In a first step you deploy opencrx-core-CRX-App.ear. Select Applications > Enterprise Applications and then click the Browse button to select the EAR file as shown below:

Figure 15: Deploy the opencrx-core-CRX-App EAR.

You can skip all screens and leave the default values until you reach Step 1: Installation options as shown below. Accept the default values and click Next.

Make sure that the option Deploy Enterprise Beans is checked. If you do not check the option, WebSphere will not generate stubs and will not be able to start openCRX.

Figure 16: Select Deploy EJBs.

You can skip all steps and leave the default values until you reach the final step Step 9: Summary as shown below. Verify the values and then click Finish.

Figure 17: Verify the deployment settings.

The deployment process must pass without any errors and warnings. If the deployment process fails you have probably not copied openmdx-kernel.jar to the directory WebSphere\AppServer\lib\ext.

Listing 3: Log of App EAR deployment.

Installing...
If there are enterprise beans in the application, the EJB deployment process can take several minutes. Please do not save the configuration until the process completes.
Check the SystemOut.log on the Deployment Manager or server where the application is deployed for specific information about the EJB deployment process as it occurs.
ADMA5016I: Installation of openCRX Core EAR started.
ADMA5067I: Resource validation for application openCRX Core EAR completed successfully.
ADMA5058I: Application and module versions are validated with versions of deployment targets.
ADMA5018I: The EJBDeploy command is running on enterprise archive (EAR) file C:\pgm\IBM\WebSphere\AppServer\profiles\AppSrv01\wstemp\514564614\upload\opencrx-core-CRX-App.ear.
Starting workbench.
framework search path: c:\pgm\IBM\WebSphere\AppServer\deploytool\itp\plugins
Creating the project.
Deploying jar gateway
Generating deployment code
Deploying jar kernel
Generating deployment code
Deploying jar security
Generating deployment code
Deploying jar ui
Generating deployment code
Invoking RMIC.
Invoking RMIC.
Invoking RMIC.
Invoking RMIC.
Writing output file
Shutting down workbench.
EJBDeploy complete.
0 Errors, 0 Warnings, 0 Informational Messages
ADMA5007I: The EJBDeploy command completed on C:\pgm\IBM\WebSphere\AppServer\profiles\AppSrv01\wstemp\wstemp\app_110cb77b542\dpl\dpl_openCRX_Core_EAR.ear
ADMA5005I: The application openCRX Core EAR is configured in the WebSphere Application Server repository.
ADMA5053I: The library references for the installed optional package are created.
ADMA5005I: The application openCRX Core EAR is configured in the WebSphere Application Server repository.
ADMA5001I: The application binaries are saved in C:\pgm\IBM\WebSphere\AppServer\profiles\AppSrv01\wstemp\514564614\workspace\cells\wfro6Node01Cell\applications\openCRX Core EAR.ear\openCRX Core EAR.ear
ADMA5005I: The application openCRX Core EAR is configured in the WebSphere Application Server repository.
SECJ0400I: Successfuly updated the application openCRX Core EAR with the appContextIDForSecurity information. ADMA5011I: The cleanup of the temp directory for application openCRX Core EAR is complete.
ADMA5013I: Application openCRX Core EAR installed successfully.

The installed application should now appear in Applications > Enterprise Applications as openCRX Core EAR. Check the application and click Start.

Next you must install the web application opencrx-core-CRX-Web.ear. The process is the same as described previously for the opencrx-core-CRX-App.ear. However, there are a few differences.

At the beginning check the option Show me all installation options and parameters as shown below. This is required to configure the security properly in the following steps.

Figure 18: Deploy the Web EAR and check show me all installation options.

In Step 1 you must select the option Pre-compile JSP as shown in the figure b elow. The web application contains Java Server Pages which must be precompiled during deployment.

Figure 19: Deploy the openCRX web application. Select Pre-compile JSP.

The web application opencrx-core-CRX defines the following security roles:

• OpenCrxUser and OpenCrxAdministrator. Users who are member of OpenCrxUser or OpenCrxAdministrator are able to login to the web application.

• OpenCrxRoot. Root users who are member of OpenCrxRoot are able to login to the web application.

The roles are defined in the deployment descriptors of the application enterprise archives and must be mapped in Step 5: Map security roles to users/groups to WebSphere users and groups. In a first step select the role, e.g. OpenCrxRoot, as shown below:

Figure 20: Assign users and groups to openCRX roles.

Then either click Lookup users or Lookup groups. Lookup users allows you to add WebSphere users to the groups OpenCrxRoot, OpenCrxAdministrator and OpenCrxUser. Lookup groups allows you to add WebSphere groups. In order that a WebSphere user is able to login to the application he/she must be member of the configured WebSphere group.

Be careful that you add to the group OpenCrxRoot only users who should have openCRX root privileges. The openCRX standard configuration assumes that you add the user admin-Root to the group OpenCrxRoot, the user admin-Standard to the group OpenCrxAdministrator, and the user guest to the group OpenCrxUser.

The figure below shows how to add the user admin-Standard to the group OpenCrxAdministrator. Also assign the users who must have access to openCRX to the group OpenCrxUser.

Figure 21: Assign users and groups to openCRX roles.

You can click Next on all the following steps and finally click Finish. If the application does not deploy without errors you cannot use openCRX; please review/correct your installation carefully until the application can be deployed without errors.

Listing 4: Log of Web EAR deployment.

Installing...
If there are enterprise beans in the application, the EJB deployment process can take several minutes. Please do not save the configuration until the process completes.
Check the SystemOut.log on the Deployment Manager or server where the application is deployed for specific information about the EJB deployment process as it occurs.
ADMA5016I: Installation of opencrx-core-CRX_war started.
ADMA5067I: Resource validation for application opencrx-core-CRX_war completed successfully.
ADMA5058I: Application and module versions are validated with versions of deployment targets.
ADMA5009I: An application archive is extracted at C:\pgm\IBM\WebSphere\AppServer\profiles\AppSrv01\wstemp\wstemp\app_110cb848605\ext
ADMA5003I: The JavaServer Pages (JSP) files in the Web archive (WAR) files client-gateway.war, opencrx-core-CRX.war, server-gateway.war compiled successfully.
ADMA5005I: The application opencrx-core-CRX_war is configured in the WebSphere Application Server repository.
ADMA5053I: The library references for the installed optional package are created.
ADMA5005I: The application opencrx-core-CRX_war is configured in the WebSphere Application Server repository.
ADMA5001I: The application binaries are saved in C:\pgm\IBM\WebSphere\AppServer\profiles\AppSrv01\wstemp\514564614\workspace\cells\wfro6Node01Cell\applications\opencrx-core-CRX_war.ear\opencrx-core-CRX_war.ear
ADMA5005I: The application opencrx-core-CRX_war is configured in the WebSphere Application Server repository.
SECJ0400I: Successfuly updated the application opencrx-core-CRX_war with the appContextIDForSecurity information. ADMA5011I: The cleanup of the temp directory for application opencrx-core-CRX_war is complete.
ADMA5013I: Application opencrx-core-CRX_war installed successfully.
Application opencrx-core-CRX_war installed successfully.

9 Final Steps

Before you proceed to the openCRX QuickStart guide make sure that you have deployed and started all applications as shown below:

Figure 22: The openCRX applications must be deployed and running.

The application is initialized the first time a user calls the login page. If the startup fails you should consult the following log files:

• WebSphere startServer.log. Located in WebSphere\AppServer\logs\server1 and contains WebSphere startup information.

• WebSphere SystemErr.log. Located WebSphere\AppServer\logs\server1 in and contains the stderr output of WebSphere and deployed applications.

• WebSphere SystemOut.log. Located in WebSphere\AppServer\logs\server1 and contains the stdout output of WebSphere and deployed applications. This file contains the informational messages of the openCRX web application startup sequence.

• openCRX opencrx-server1…log. Located in WebSphere\AppServer\logs\server1 and contains the openCRX application log files.

License

The contents of this file are subject to a BSD license (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.opencrx.org/license.htm

Copyright 2007 © CRIXP Corp. All rights reserved.