Basic Rational DOORS Web Access installation

Suggested minimum physical setup

Comments

Prerequisites

Figure 1 is the basis of this article and the minimum configuration setup that we would expect to find in a customer site. Because this article is about the IBM® Rational® DOORS® Web Access product, the assumption is that you already have a successful installation of the core product, the Rational DOORS client and server.

Visually, we will start at the DOORS Web Access server component and work our way up the image through the components.

Figure 1. Diagram of the recommended installation
Component-oriented layout of suggested installation
Component-oriented layout of suggested installation

DOORS Web Access server

The DOORS Web Access server is a Java application, and the first tier of the architecture. The server requires the most configuration to achieve the expected connectivity and performance.

JVM memory allocation

The file at this location contains the startup code for the DOORS Web Access server Java Virtual Machine (JVM):

C:\\Program Files\ibm\Rational\ DOORS Web Access\1.5.0.0\server.start.bat

One of the Java parameters in this file is -Xmx, which defaults to 512 MB at installation, because we cannot assume that our customers are installing on servers with large capacities. However, we suggest that you increase this to 1536 MB if at all possible. This allows the memory self-management capability of the JVM more overhead, which improves performance. A JVM with this memory allocation will handle up to 100 heavy users with only slight performance deterioration.

Necessary file changes

As part of the standard installation, there are three possible changes to make in the festival.xml file that you can find at the following location:

C:\\Program Files\ibm\Rational\ DOORS Web Access\1.5.0.0\server\festival\config\festival.xml

The three parameters for basic connectivity are covered in the standard installation instructions, but there are here to make this article complete:

  • The repositoryUrn variable needs to be changed to your DOORS repositoryUrn so that DOORS Web Access can find the correct database.
  • The license.server.location variable needs to be changed to your company's information.
  • Lastly, if the DOORS Web Access Broker is located on a separate server, the two localhost (127.0.0.1) statements need to be changed to the DOORS Web Access Broker location.

Interop server

The Interop server component of the Rational DOORS Web Access stack is a modified traditional client. This means that it is a single-threaded application, and this has significant ramifications for the layout of this tier (see Required number of Interop servers).

Interop servers can be launched as a service but, in testing, we launch the Interop servers using shortcuts. This shortcut is a DOORS shortcut with modifying command arguments.

Enabling Interop servers

In the target line in a DOORS shortcut, add the following command:

-interop

This commands the DOORS.exe to launch as an Interop server, rather than the client.

Required number of Interop servers

Due to the single-threaded nature of the Interop servers, having a single Interop server is never sufficient. Only one request can be processed at a time by an Interop server; therefore, any concurrency will lead to significant degradation of DOORS Web Access performance unless the servers are clustered.

The minimum number of Interop servers that we suggest for any installation is 4.

The -maxMemory option

The Interop servers cache data to improve performance, and they retain that data for a period of time. This results in an increasing memory use for the Interop server, and this memory use is limited only by the memory allocation for each process at the operating system level. On a 32-bit operating system, this is 2 GB. The recommended nest of 4 servers can consume a total of 8 GB of RAM. If the server that they are deployed on has less than this, the operating system will start virtual page swapping, which affects performance.

Therefore, we expect that all active Interop servers have the –maxMemory command defined at startup. This command will restart the individual Interop server with no loss of transaction or connectivity.

We suggest that you check the available RAM on the server that the 4 Interop servers are to be run on, and then divide this by 4 so that all of the Interop servers can be at their maximum memory allocation without affecting performance.

The command is –maxMemory, followed by the amount of RAM in MB that you are willing to allow. For example:

-maxMemory 512

Enabling logging

To enable logging, use the –l command followed by the location and name of the log file that you want, in quotation marks. For example:

-l "c:\\logfging\mylog.log"

Logging level

The -logLevel command sets the level of data captured by the Interop servers while they are active. The two most commonly seen levels are 7 and 8, where 7 records the transaction headers and 8 records full data passed through the server. These should be enabled only under the advice of IBM technical support.

Brokerhost location

The -brokerHost command allows the Interop server to find the DOORS Web Access Broker if it is installed on a separate server. The server name or IP address should be in quotation marks:

-brokerHost "myBrokerLocation"

Lightweight server option

The -lightServer command instructs an individual Interop server not to service any module open commands. This means that there is always a server available to handle lighter load tasks, such as authenticating login.

We suggest that one Interop server in each nest should have this enabled.

Fully constructed command

This is the fully constructed command for launching an Interop server with logging enabled (excluding -lightServer):

"C:\Program Files\ibm\Rational\DOORS\9.4\bin\DOORS.exe" -interop -l 

"C:\\logging\mylog.log" –logLevel 7 –brokerHost "myBrokerLocation" -maxMemory 512

Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=812335
ArticleTitle=Basic Rational DOORS Web Access installation
publish-date=05012012