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\18.104.22.168\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\22.214.171.124\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 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:
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:
-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 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
"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 the developerWorks weekly email newsletter, and choose the topics to follow.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
- Get the free trial download for Rational DOORS Web Access.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.