TN0033: Installing Jazz Team Server with WebSphere Application Server

Last Updated: October 31, 2008
Author: Daniel Kogan

CONTENT DEPRECATED

For more current instructions, see Tech Tip: Installing Rational Team Concert 2.0 with WebSphere Application Server 6.1.0.25 / 7.0.0.3.

Summary

In this Tech Tip we will provide step by step guidance of how to setup Jazz Team Server to run with WebSphere Application Server, including discussion on application server configuration, group management, security setting, application deployment and start-up.

The purpose of this Tech Tip is to help users, less familiar with WebSphere Application Server, to quickly deploy Jazz using local file authentication for testing and LDAP server for the real role-based authentication schema. Experienced WebSphere Application Server administrators can probably use the full product documentation.

One of the biggest challenges configuring WebSphere Application Server with or without LDAP is to properly setup the server security options, provisioning information, JVM arguments, groups information and, in case of standalone LDAP realm, the LDAP filters information before the actual Jazz server deployment as it is known to cause some difficulties in deploying Jazz without proper initial setup.

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

Note

In case when jazz is initially installed, reinstalled or server global setting are modified the 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 is removed.

More Information

Jazz Pre-install requirements

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

1. Start with downloading and installing Standard or Full version of Jazz server. If Jazz server is already install find the location of the installation. You will need to change some of the configuration and properties files for WebSphere Application Server configuration.
2. First we modify the provision files. Assuming that the installation path is <Your Path><JazzTeamServer instance name>/ location, you need to convert all the directory paths inside following files into the URL form (file:///path):

   		file:///<Your Path><JazzTeamServer instance name>/server/provision_profiles/license-profile.ini
   		file:///<Your Path><JazzTeamServer instance name>/server/provision_profiles/profile.ini
   		

3. The next step would be to change the relative paths in these files into the full file paths.

   		file:///<Your Path><JazzTeamServer instance name>/server/teamserver.properties
   		file:///<Your Path><JazzTeamServer instance name>/server/log4j.configuration
   		

   For example:

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

   Needs to be changed into

   com.ibm.team.repository.db.jdbc.location = C:Program FilesIBMJazzTeamServer 1.0serverrepositoryDB

Note

• For Windows only, the converted paths in the provision_profile directory should either contain no spaces or be changed into Windows 8.3 file format ( ex. file://C:/Program Files would be changed into PROGRA~1 )
• The directory containing provision profiles (typically file:///<Your Path><JazzTeamServer instance name>/server/provision_profiles) should contain only 2 files: license-profile.ini and profile.ini. Do not store any backups in the profile directory as the process reads ALL files in that directory

WebSphere Requirements

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

1. Install IBM WebSphere Application Server, at least version 6.1.0.0.
2. Download the “Jazz Server Setup Guide”. (https://jazz.net/downloads/rational-team-concert/releases/1.0?p=install.docs/install_standard_zip).
3. Follow Websphere Installation in the “Jazz Server Setup Guide” to verify that your database is configured properly, that the Jazz server runs properly. Verify the installation before setting up the security.
4. Once you�ve verified that you can display a URL similar to http://localhost:9080/jazz/web/projects/My Project in the web client, you are ready to setup the security in WebSphere Application Server.

JVM Setup

Whether running WebSphere Application Server with or without LDAP the JVM and Security Settings need to be properly setup first:

1. The first and foremost task is to load the Jazz properties files into WebSphere Application Server JVM. There are 2 ways to do it: via JVM Custom properties and JVM Generic Arguments.

   Please note that JVM Generic Arguments setup is deprecated and is shown here only to support tutorials and guides that mention it.

2. In the WebSphere Application Server Admin Console click Application Servers menu option in the left menu column

   

3. Then choose the App Server (server1) in this case.
4. Click Java and Process Management.

   

5. Click Process Definition.



6. Click Java Virtual Machine.

   

Provisioning via “JVM Custom Properties” (recommended)

1. Click Custom Properties

   

2. Click the new

   

3. Define 3 Properties by providing name, value. Click Apply.

   

4. Need to set the correct path for these jvm properties:
   • com.ibm.team.repository.provision.profile: file:///
   • com.ibm.team.server.configURL: file:///
   • log4j.configuration: file:///

   So that at the end it looks like this:

   

Note

Provisioning via “JVM Generic Arguments” (deprecated)

JVM Generic Arguments setup is mentioned here only in case you already set it up following one of the earlier install guides.

• From the “Process Definition” link click on JVM, add this to “Generic JVM arguments” as 1 line:

  	-Dcom.ibm.team.server.configURL=file:////server/teamserver.properties
  	-Dlog4j.configuration=file:/// /server/log4j.properties
  	-Dcom.ibm.team.repository.provision.profile=file:/// /server/provision_profiles 
  	

  

Note

• For Windows only, the converted paths in the provision_profile directory should either contain no spaces or be changed into Windows 8.3 file format ( ex. file://C:/Program Files would be changed into PROGRA~1 )
• We recommend that you delete the JVM Generic Arguments and setup the Custom properties

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 Secure Administration, applications, and infrastructure Servers menu option in the left menu column.

   

2. Make sure the following security settings are configured in the main window:
   • Enable administrative security is “on”
   • Enable application security is “on”
   • Java 2 security is “off” for all 3 options
3. Save the master configuration and restart the WebSphere Application Server process

Authentication Setup

Jazz uses J2EE container managed authentication for login and system permissions. For application security to work, you must configure a realm with the application server. For full application functionality, including viewing system user roles and importing users, Jazz supports an LDAP realm. If you are just testing, however, you can also configure a file based realm for application security. This realm will then be used for authentication and authorization, but Jazz will not be able to query what roles a user has or import users. The following Configuring WebSphere Application Server with Federated realm Tech Tip will show you how to configure the file based realm for application security.

For LDAP-based configuration, read the Tech Tip 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

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.

   If you used the “Install without Tomcat” option the “jazz.war” archive would appear under <Your Path><JazzTeamServer instance name>/server/jazz.war directory.

   If you used the “Install with Tomcat” option it would be under <Your Path><JazzTeamServer instance name>/server/tomcat/webapps/jazz.war directory.

   

3. Put “/jazz” as the Context root and select the option Show me all installation options and parameters.

   Note

   Unless “Show me all installation options and parameters” option is chosen it will not be possible to setup the group mappings and Jazz would not operate properly.

4. Press Next or Continue until Step 6.
5. In step 6 (Map Virtual Hosts), make sure that that Mapping to the default host checkbox is selected.
6. Press Next or Continue 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 on Look up groups button.



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



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



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.

Note

•  To check if the application was properly installed click on Enterprise Applications 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.

• 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 app put the check mark against the Jazz app and click on the start button.

Ports Setup

This step will teach you how to verify and/or change the ports that Jazz server uses for the web-based administration.
Follow this Tech Tip to learn about Web-based Jazz administration.

1. To determine or change the ports click on the Application Servers link on the left menu and then choose the server. On the Server page expand the Web Container and pick Web container transport chains link

The value of WCInboundDefaultSecure property would indicate the secure port for admin connection in the Jazz Web UI (9443 in this case).

Note

1. Login to jazz server Web-based administration page to configure Jazz server and verify proper installation. 
2. If WebSphere Application Server was setup to run with LDAP go to the setup page https://:/jazz/setup to configure Jazz to run with LDAP server. 
3. Please follow this link for additional information on Web-based administration and setup.

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>tomcatlogsjazz.log
• <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2> server1logsSystemOut.log
• <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2> server1logsSystemErr.log

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

The Jazz.log file by default would be located in <Installation Path>IBMWebSphereAppServer<N1>tomcatlogs directory as defined in log4j.properties file

Example:
log4j.appender.file.File=tomcat/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. One more directory that needs a clean-up is
   <Installation Path>IBMWebSphereAppServer<N1>profilesAppSrv<N2> wstemp

References

Links and related topics:

• Full product documentation for the Experienced WebSphere Application Server administrators
• Windows 8.3 file format
• Configuring WebSphere Application Server with Federated realm
• LDAP realm setup
• Web-based Jazz administration