Jazz Library Tip: Installing Rational Team Concert 2.0 with WebSphere Application Server 6.1.0.25 / 7.0.0.3
Author name

workflow-management,jazz-foundation,rational-team-concert

Tue, 10 Nov 2009
5 min read
0

Tip: Installing Rational Team Concert 2.0 with WebSphere Application Server 6.1.0.25 / 7.0.0.7

Published: September 3, 2009 (Updated November 10, 2009)
Authors: Christophe Elek, Eric Jodet, Matt Lavin

Summary

In this article we will provide step by step guidance of how to setup RTC 2.0 to run with WebSphere Application Server 6.1.0.25 / 7.0.0.7.

Application server configuration, group management, security setting, application deployment and start-up, is discussed in technote Installing Jazz Team Server with WebSphere Application Server.

The purpose of this article is to help users, less familiar with WebSphere Application Server, to quickly deploy RTC using local user registry authentication for testing. However, for the real role-based authentication schema, we encourage to use LDAP server authentication.

Experienced WebSphere Application Server administrators can use the RTC 2.0 InfoCenter instead of this article.

The mains steps to follow are:

  1. Verify Websphere requirements
  2. Copy RTC files to your WAS directory
  3. Modify RTC configuration files to match your installation settings
  4. Set-up the JVM parameters
  5. Deploy the RTC application
  6. Complete the setup

This guide was created using IBM WebSphere Application Server, 7.0.0.7 and Integrated Solutions Console, 7.0.0.7 on Windows. All the paths provided are Windows paths and need to be changed if deployed on other OS platforms.
Notes

  1. This also applies to WebSphere Application Server 6.1.0.25. Differences of setup are noted.
  2. In case when jazz is initially installed, reinstalled or server global setting are modified certain care needs to be taken for the running instance of WebSphere Application Server. It is suggested to shutdown the WebSphere Application Server process and then restart it. In case of uninstall, it is also recommended that the folder containing the ear/war files as well as the temporary directory is removed.
  3. If upgrading from RTC 1.X to RTC 2.0, please read the upgrade instructions available on jazz.net.

Detailed Instructions

WebSphere Requirements

For the complete WebSphere installation guide please visit the WebSphere Information Center.

  1. Download WebSphere Application Server version 7.0.0.0 (or download the version 6.1.0.0)

    6.1: Click on the link below to learn how to download and install WebSphere Application Server
    http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27007435
    WebSphere Application Server V6.1 for AIX 5L V5, 32-bit support (C1Y2BML)
    WebSphere Application Server V6.1 for AIX 5L V5, 64-bit support (C1Y2CML)
    WebSphere Application Server V6.1 for Linux on x86Series 32-bit,Multilingual (C87QXML)
    WebSphere Application Server V6.1 for Linux on x86-64, 64-bit, Multilingual (C87R0ML)
    WebSphere Application Server V6.1 for Windows 2000, Windows Server 2003, 32bit, Multilingual(C87QTML)
    WebSphere Application Server V6.1 for Windows Server 2003 x64, 64-bit, Multilingual (C92VSML)

    7.0: Click on the link below to learn how to download and install WebSphere Application Server
    http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27012961
    IBM WebSphere Application Server V7.0 for AIX on PowerPC 32-bit, Multilingual (C1G0XML)
    IBM WebSphere Application Server V7.0 for AIX on PowerPC 64-bit, Multilingual (C1G11ML)
    IBM WebSphere Application Server V7.0 for Linux on x86 32-bit, Multilingual (C1FZ6ML)
    IBM WebSphere Application Server V7.0 for Linux on x86-64 bit, Multilingual (C1FZ9ML)
    IBM WebSphere Application Server V7.0 for Windows on x86-32 bit, Multilingual (C1G0QML)
    IBM WebSphere Application Server V7.0 for Windows on x86-64 bit, Multilingual (C1G0TML)
  2. Install IBM WebSphere Application Server version 7.0.0.0 (NOTE: for 6.1.0.25, check the RTC 2.0 InfoCenter for how to obtain the required fixes)
  3. Install IBM WebSphere Application Server FixPack 7 and  corresponding JVM update.
  4. Verify that WAS Server is at expected required level (7.0.0.7)

    WAS 7.0.0.3

  5. If using IBM JRE, please read this Tech Note.

Jazz Pre-install requirements

This section will show you all necessary preparation steps prior to installing Jazz with WebSphere Application Server.

  1. Ensure the RTC has been installed.
    • If the RTC server was not already installed (referred from here on as Install Without Tomcat) download and install the desired version of RTC.

      When using the IBM® Installation Manager the Jazz Team Server files can be installed into a web application directory. During the installation process, you should not install the included Apache Tomcat application server; this makes the Installation Manager ask for a Web Application directory and install only the files needed for WebSphere. The installation directory is referred to as JazzInstallDir in this procedure. If you use the IBM Installation Manager to install the files into the WebSphere Application Server Web applications directory, then you do not need to manually move the files as described below.

    • If the RTC server was already installed as a stand alone and not into a web application directory (referred from here on Install with Tomcat) then you are ready to proceed.

      The RTC includes the files required to run a complete Apache Tomcat-based server. For a WebSphere installation you only need a subset of theJazz Team Server files and you should place them in a directory on your WebSphere server machine. Further instructions refer to this as the Jazz Team Server installation directory, or JazzInstallDir for short. From this directory, use:

      • The file JazzInstallDir/server/tomcat/webapps/jazz.war.
      • The directory JazzInstallDir/server/update-site.
      • The directory JazzInstallDir/server/conf.
      • The default repository database in JazzInstallDir/repositoryDB.
      • The repository tools in JazzInstallDir/repotools.
      • The directory JazzInstallDir/server/license-update-site.
      • The directory JazzInstallDir/server/nl1-update-site.
      • The directory JazzInstallDir/server/nl2-update-site.
  2. The next step would be to change the relative paths in these files into the full file paths. 
    file:///<JazzInstallDir>/server/conf/jazz/teamserver.properties

    For example: 

    com.ibm.team.repository.db.jdbc.location = repositoryDB

    Needs to be changed into 

    com.ibm.team.repository.db.jdbc.location = D:/RTC20ForWAS/server/repositoryDB

Java Virtual Machine Setup

Setup RTC specific JVM properties.
  1. From the WebSphere Administration console, click on Servers > Application Servers on V6 or Servers > Server types > WebSphere Application Servers on V7.
  2. Select the Application Server to which RTC will be deployed, generally server1.
  3. Expand Java and Process Management and click on Process Definition
  4. Click on Java Virtual Machine
  5. Click on Custom Properties
  6. Click on the New button:

    New Property

  7. Add the new JAZZ_HOME property and set the value to file:///[JazzInstallDir]/server/conf and click OK.
    For example: file:///D:/RTCServerForWAS/server/conf

    JAZZ_HOME

  8. In the same way, add the following properties:
    Name: java.awt.headless Value: true
    Name: org.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin Value: true
  9. Note: If you are connecting to an Oracle or SQL Server database then you need to add a property named “ORACLE_JDBC” or “SQLSERVER_JDBC”. Please refer to the InfoCenter for detailed instructions.
  10. Save your changes – the JVM Custom Properties page should now look like:

    JVM Properties

  11. Click the Java Virtual Machine link at the top of the page.
  12. Add the value 100 to the Initial Heap.
  13. Add the value 1000 to the Maximum Heap Size.
  14. Click on Apply.
  15. Click on Process Definition link at the top of the page.
  16. Click on Logging and Tracing. Click Change Log Detail Levels. The Jazz Team Serveruses the BIRT reporting engine. To prevent BIRT informational entries from being written to the WebSphere log file, set the logging level to severe for the org.eclipse.birt.* packages. Click on Apply.

  17. Click Save directly to the master configuration.

Security Setup

In this section we are going to setup some of global WebSphere Application Server instance properties and activate proper security settings.

WebSphere Application Server Security Setup

  1. In the WebSphere Application Server Admin Console go to Security > Secure Administration, applications, and infrastructure on V6 or  Security > Global Security for V7.
  2. Make sure the following security settings are configured in the main window:
    • Enable administrative security is “on”
    • Enable application security is “on”
    • Use Java 2 security is “off” for all 3 options

    security

  3. Ensure that the WAS security setting “Use available authentication data when an unprotected URI is accessed” is checked. Do this by:
    • Navigating to Security > Secure Administration, applications, and infrastructure on V6 or  Security > Global Security for V7
    • Expanding Web Security on V6 or Web and SIP Security on V7
    • Clicking General Settings.
    • Selecting the checkbox for “Use available authentication data when an unprotected URI is accessed”.

    Web Security

  4. Click OK and Save the master configuration.
  5. Restart the WebSphere Application Server process

Authentication Configuration

Jazz uses J2EE container managed authentication for login and system permissions. For application security to function, you must configure a realm with the application server. We recommend using and configuring another LDAP realm.

For full application functionality, including viewing system user roles and importing users, some Jazz server support an LDAP realm.
The following Configuring WebSphere Application Server with Federated realm article will show you how to configure the file based realm for application security.

For LDAP-based configuration, read the article about Configuring WebSphere Application Server with LDAP realm to configure WebSphere Application Server instance to use LDAP server for the users’ roles assignment and authentication mechanism.

Application Deployment

In this section we will deploy JAZZ using either local file-based authentication with Federated realm or LDAP-based authentication with Standalone LDAP realm. At this point make sure that the security settings are properly activated, and the realm is configured. Verify that the groups and users are created if you use the local file authentication or that LDAP server communication is setup and tested if you use the LDAP-based authentication.

Installation for 7.0.0.7

  1. To install the Jazz Team Server, click Applications > New Application > New Enterprise Application from the left menu.

    Install New Application

  2. In the Install Application Screen click Browse to bring up the file chooser dialog box to pick the jazz.war file.

    Please note that the default location of the “jazz.war” file depends on how you installed the Jazz server.

    The “jazz.war” archive would appear under <Your Path><JazzTeamServer instance name>/server/jazz.war directory, if you have followed the “Install without Tomcat” option,.
    The “jazz.war” archive would appear under <Your Path><JazzTeamServer instance name>/server/tomcat/webapps/jazz.war directory, if you have followed the “Install with Tomcat” option,.

    Select WAR file

  3. Select Detailed installation option, click Next and then Continue button.
  4. Step 1: keep the default settings and click Next button.
  5. Step 2: select jazz.war module

    Step 2

  6. Press Next until Step 7.
  7. Step 7: (Map Virtual Hosts), make sure that that Mapping to the default host checkbox is selected

    Step 7

  8. Step 8: Put “/jazz” as the Context root

    Step 8

  9. Press Next until Step 9.

    At this point the jazz deployment descriptor was read and now we need to map Jazz groups and users.
    The mapping instructions are described in the next section called “Group Mapping”.

Installation for 6.1.0.25

  1. To install the Jazz Team Server, click Applications > Install New Application from the left menu.
  2. In the Install Application Screen click Browse to bring up the file chooser dialog box to pick the jazz.war file.

    Please note that the default location of the “jazz.war” file depends on how you installed the Jazz server.

    The “jazz.war” archive would appear under <Your Path><JazzTeamServer instance name>/server/jazz.war directory, if you have followed the “Install without Tomcat” option,.
    The “jazz.war” archive would appear under <Your Path><JazzTeamServer instance name>/server/tomcat/webapps/jazz.war directory, if you have followed the “Install with Tomcat” option,.

  3. Enter jazz as a context root, then select Show me all installation options and parameters instead of Detailed, then click Next and then Continue button.
  4. Step 1: keep the default settings and click Next.
  5. Click Continue then select Step 2.
  6. Step 2: select jazz.war module
  7. Click Next until Step 6.
  8. Step 6: (Map Virtual Hosts), make sure that that Mapping to the default host checkbox is selected.
  9. Step 7: Put “/jazz” as the Context root
  10. Click Next until Step 8.

    At this point the jazz deployment descriptor was read and now we need to map Jazz groups and users. The mapping instructions are described in the next section called “Group Mapping”.

Group Mapping

This step will create mappings between groups information in Jazz and groups information in WebSphere Application Server. In case of a setup with Federated realm, the groups were created manually and with LDAP realm they were mapped from the LDAP server.

  1. For each of the displayed groups, check mark one group at a time and click Map Groups or Lookup Groups button depending on your version

    Mapp Groups

  2. In the Search String box type in <String of the group to search>* and hit search button (only one time for the first mapping, after that the group names would be cached).

    Select Group

  3. Click on the “>>” button to choose the corresponding group and click OK. Repeat the procedure for all created groups. After mapping all 4 groups the group mapping screen should look like this:

    All Groups Mapped

  4. Press Next, followed by Finish.
  5. After successful deployment, you will see output like the one on the following snapshot. To complete the installation, save the new configuration.

    deploy

Note

  • To check if the application was properly installed click on Enterprise Applications on V6 or WebSphere Enterprise Applications on V7 link in the left menu. The Jazz application should be there with the red “x” indicating that it was not started. If you see the empty circle (as below), this indicates that configuration was not saved into the master configuration.
Save changes
  • In this case click on Save link to persist the settings.

Post Deployment and Jazz Startup

This step will start the Jazz server in WebSphere Application Server and mention the log files to check in order to verify the normal Jazz startup.

  1. To start the application, select the Jazz application and click the Start button.

    Start RTC

  2. Verify the jazz application was started:

    Application started

Logs

This step will show where to find the log files with additional information on Jazz startup and operations information.

If Jazz comes up with errors or Web UI cannot connect at all the best place to start troubleshooting is to look at 3 log files (2 WebSphere Application Server log files and 1 Jazz log file).
To verify that provisioning was done correctly look at the jazz.log file.

  • <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2>logsjazz.log
  • <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2>logsserver<N3>SystemOut.log
  • <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2>logsserver<N3>SystemErr.log

Where N1, N2 and N3 are the instance numbers ( if installed only once usually have both values of 1 )

The jazz.log file location is defined in the [JazzInstallDir]/server/conf/jazz/log4j.properties file.

Example:
log4j.appender.file.File=logs/jazz.log

Cleaning the temp directories

This step will show how to cleanup the previous Jazz installation in case of either installation failure or a complete reinstall.

  1. As mentioned before when any part of installation fails or Jazz does not come up, it is recommended to uninstall the server, shutdown the WebSphere Application Server process and clean the ear directory.
    The default location of jazz ear directory is
    <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2>installedAppsIBM-<WEBSPEHERE NODE AND CELL NUMBER>Celljazz_war.ear
    Delete this directory.
  2. Two more directories that needs a clean-up are
    <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2>wstemp
    <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2>tempNode<N3>Server<N4>jazz_war

Proceed with set-up

Refer to the InfoCenter page to proceed with installation and RTC server setup.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Tue, 10 Nov 2009