Basic Rational DOORS Web Access installation
Suggested minimum physical setup
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
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\22.214.171.124\server.start.bat
One of the Java parameters in this file is
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\126.96.36.199\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.
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:
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
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:
To enable logging, use the
–l command followed by the location
and name of the log file that you want, in quotation marks. For
-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 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:
Lightweight server option
-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
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
"C:\Program Files\ibm\Rational\DOORS\9.4\bin\DOORS.exe" -interop -l "C:\\logging\mylog.log" –logLevel 7 –brokerHost "myBrokerLocation" -maxMemory 512
- You can find more detailed configuration instructions and load balancing guidance in this article: Steps to scale load balancing in Rational DOORS Web Access: Configure any environment, and scale the installation to handle larger loads by Lee J. Byrnes, the author of this article (IBM developerWorks, 2011).
- Browse the Rational DOORS developerWorks page for links to technical articles and many related resources, and explore the instructions in the Rational DOORS Information Center, including the section about Installing Rational DOORS Web Access.
- Subscribe to a developerWorks newsletter, and choose which topics to follow.
- Get the free trial download for Rational DOORS Web Access.
- Evaluate IBM software.