Introduction

During a typical
day, a WDK developer will deploy new code to the application server and restart it many times. Performing
these tasks on a remote server or one shared with other developers requires extensive coordination and isn’t practical for the
rapid cycles required to develop WDK applications. It is recommended that a developer have his/her own instance
of the application server.

Developers can install the application server and the Documentum software on their development machine.
Unfortunately, only a single configuration can be installed on the machine. This is a problem
for developers who need to support multiple versions of the software for different projects or
during upgrades.

WDK developer server packs (refered to in this article simply as
server packs
)
provide a convenient way to package all of the
software required for a complete developer instance of the application server and related tools. Server packs are self-contained
structures which are easily copied from one machine to another enabling an entire team to share a single server
configuration during development. Server packs don’t require software to be installed or global settings to be made on the
machine on which they run.

The self-contained nature of server packs makes them ideal for developers working in dynamic environments where the developer
is working with multiple applications with multiple server configurations.

In this article we’ll review what goes into a server pack, how to build one, and how best to leverage server packs to enable your
team to be faster and more productive.

What is a server pack?

A server pack is a collection of all of the software required to run an instance of an application server configured to run WDK-based
applications. The software is pre-installed and pre-configured to run with relative paths and without additional machine configuration.
This facilitates running multiple instances of the application server for different projects and makes copying the entire server environment
from one machine to another possible.

A server pack contains at a minimum:

• JDK/JRE
• Application server (eg. Tomcat)
• DFC
• Base WDK application (eg. Webtop or DA)
• Startup script

Additionally, a server pack may also contain any other software necessary for the application server environment (for example, alternate
JSP compilers or third-party tools or the Documentum Java Method Server).

The goal of the server pack is to have a self-contained directory structure that can be zipped up and copied from machine to machine
or moved on the same machine with minimal complication. As we will see, this is less complicated to get set up than it may initially
sound.

Sample Environment

This article will outline the server pack creation process for a Webtop 5.2.5sp2 server running on Tomcat 4.1.27 on Windows 2000 Server.
This environment is suitable for most developers. It is possible to create server packs for Linux or Solaris or which utilize alternate
application servers. A Win32 platform is appropriate for most developers and we’ve found that there are relatively few portability
issues in developing for Tomcat and deploying on alternate application servers (i.e. Websphere or SunOne). Tomcat has proven
to be relatively easy to work with and has good community support and is one of the earliest platforms that WDK-based applications
are released on.

Building a server pack

There is no magic involved in putting together a server pack. The process basically involves (1) installing the software needed to
run the application server in a clean environment, (2) poaching the required files out of that environment, and (3) updating the configuration
and startup scripts to work in the new server pack structure. Creating the first server pack is a bit tedious and may take
some time. Creating future server packs will typically only require minor tweaks of the original server pack and will go very quickly.

Step 1: Start with a clean environment

The first step is to start with a clean environment suitable for running the application server. This should
correspond to the platform on which the server pack will be used. For most developers this is Windows XP or Windows
2000. It is certainly possible to create a server pack for another platform (i.e. Solaris) but we’ve found that most
developers have a Win32 platform on their desks. The reason for starting with a clean environment is to ensure that only
the files needed for the server pack end up in the server pack.

At Blue Fish, we utilize VMWare to maintain environments like this. VMWare let us have a
“clean” environment without a separate physical machine. It also enables us to revert back to a known clean environment when
we are done installing the application server software. This can, of course, be done with a physical machine but the process
is more laborious each time you want to create a new server pack.

Step 2: Install the JDK

Install an appropriate version of the JDK (or JRE). For our sample environment we’ll install JDK 1.4.1_07.
It defaults to C:j2sdk1.4.1_07. That’s fine for us.

Step 3: Install Tomcat

Install the application server. For the sample environment that is Tomcat 4.1.27. If there is other
software that the application server requires, install that too. We’ll extract the Tomcat ZIP file to C: which
creates a C:jakarta-tomcat-4.1.27

Step 4: Install Webtop

This will install DFC and the Webtop application.

During the installation, you will need to specify the location of the Documentum software. This is where the JAR files
and DLLs will be installed.

During the installation, you will also need to specify the location of the user directory. This is where the config directory will be found.

Finally, specify where the Tomcat instance is installed.

Step 5: Create Server Pack Structure

Create a directory to hold the Server Pack. For our purposes, we’ll create C:WebtopServerPack5.2.5sp2.

Step 6: Poach the JDK/JRE

Copy the entire JDK directory C:j2sdk1.4.1_07 into the server pack directory creating the directory
C:WebtopServerPack5.2.5sp2j2sdk1.4.1_07

Step 7: Poach the Webtop Web Application

We’ll move the webtop web application out of the %CATALINA_HOME%webapps directory to make it more
convenient to work with in the future.

Move the webtop directory to the server pack directory %CATALINA_HOME%webappswebtop becomes
C:WebtopServerPack5.2.5sp2webtop

Step 8: Poach the Tomcat Install

Copy the tomcat directory (which no longer contains the webtop web application) to the sever pack directory creating
C:WebtopServerPack5.2.5sp2jakarta-tomcat-4.1.27

Step 9: Poach the DFC Install

Create a directory for the DFC install in the server pack directory. We’ll create C:WebtopServerPack5.2.5sp2dfc.

There are three sets of files which need to be copied to collect the DFC installation.

1. The first set is the DLLs or shared libraries. The author usually copies these into a subdirectory of the server pack’s DFC
   installation. We’ll create C:WebtopServerPack5.2.5sp2dfcwin32. Putting the platform-specific files in a
   subdirectory leaves the option open of building a server pack that would be easier to configure for multiple platforms.
   For our example server pack, we’ll just put the DLLs in the win32 directory and leave it at that.
   Copy the DLLs from C:Program FilesDocumentumShared to C:WebtopServerPack5.2.5sp2dfcwin32.
2. The next set is the JAR files necessary for DFC. Copy the JAR files from C:Program FilesDocumentumShared
   to C:WebtopServerPack5.2.5sp2dfc.
3. The final set is the config directory containing the dfc.properties, log4j.properties, and
   dbor.properties. In our sample installation, this is located at C:Documentumconfig.
   Copy this directory to the top level of our server pack directory creating C:WebtopServerPack5.2.5sp2config

The basic components of the server pack are now in place. Now we have to configure it.

Step 10: Configure Tomcat

Earlier, we moved the webtop directory out of the webapps directory and into a top-level directory in the server pack.
In order for Tomcat to be able to find the webtop web application, we need to add a Context
to the tomcat server.xml file. Edit C:WebtopServerPack5.2.5sp2jakarta-tomcat-4.1.27confserver.xml
and add a Context element with a relative path to the webtop directory (relative to the Tomcat configuration directory).

                
<!-- Very basic server.xml as an example -->
<Server port="10080" shutdown="SHUTDOWN" debug="0">
  <Service name="Tomcat-Standalone">
    <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
               port="80" minProcessors="5" maxProcessors="75"
               enableLookups="true" redirectPort="8443"
               acceptCount="100" debug="0" connectionTimeout="-1"
               useURIValidationHack="false" disableUploadTimeout="true" />
    <Engine name="Standalone" defaultHost="localhost" debug="0">
      <!-- Global logger unless overridden at lower levels -->
      <Logger className="org.apache.catalina.logger.FileLogger"
              prefix="catalina_log." suffix=".txt"
              timestamp="true"/>
      <Host name="localhost" debug="0" appBase="webapps"
       unpackWARs="true" autoDeploy="true">
          <!-- Context for webtop -->
          <!-- This is required for the server pack example -->
          <Context path="/webtop" docBase="../../webtop" debug="0"/>
          <!-- Context for Java Method Server -->
          <!-- This is an optional context for using the server pack -->
          <!-- to run the Java method server -->
          <Context path="/DmMethods" docBase="../../DmMethods" debug="0"/>
      </Host>
    </Engine>
  </Service>
</Server>

Step 11: Create Startup Script

A startup script is required for starting the application server. Different application servers will require different
scripts. For our sample environment, we’ll create a batch file (we’re running Tomcat on Windows). A sample startup batch
file is provided for download, here.

Note:
The link is to a batch file (startServer.bat). Simply saving it to your hard drive is a safe activity and
should be permitted by your web browser.

Tomcat 4 has a startup script called catalina.bat. We have chosen to use a separate script for a couple of reasons.
A separate script limits the number of changes to application components (Tomcat in this case) within the server pack. This is
prefered as it makes it more clear where changes should be made and makes upgrading or replacing those application components
with new ones easier.

Below is an excerpt from the startupServer.bat script. The section reproduced below is the section that may
require updating with relative paths to the server pack components.

rem ************************************************************************
rem * Edit the following section for the server pack environment
rem * Where possible make paths relative to the root of the server pack
rem * %SERVERPACK_HOME% for easy portability
rem ************************************************************************
set SERVERPACK_JAVA_HOME=%SERVERPACK_HOME%j2sdk1.4.1_07
set SERVERPACK_CATALINA_HOME=%SERVERPACK_HOME%jakarta-tomcat-4.1.27
set SERVERPACK_BOF_HOME=%SERVERPACK_HOME%bof
set SERVERPACK_DFC_DATA=%SERVERPACK_HOME%DFC5.2.5sp2
set SERVERPACK_DFC_CONFIG=%SERVERPACK_HOME%config
rem *** A server pack-specific dmcl.ini is often useful
rem set DMCL_CONFIG=%SERVERPACK_HOME%dmcl.ini
set SERVERPACK_DEBUG_TRANSPORT=dt_socket
set SERVERPACK_DEBUG_ADDRESS=4000
set SERVERPACK_PATH=%SERVERPACK_DFC_HOME%win32
rem *****
rem * You will need to update the classpath for the specific WDK application you are running. Copy from catalina.bat (after WDK install)
rem * and replace absolute paths with paths appropriate for the server pack (relative to %SERVERPACK_HOME%). It is broken over several
rem * lines to make it more readable.
rem *****
set SERVERPACK_CLASSPATH=%SERVERPACK_BOF_HOME%sampleBofTypes.jar;
%SERVERPACK_BOF_HOME%servlet.jar;%SERVERPACK_DFC_CONFIG%;
%SERVERPACK_DFC_DATA%dfc.jar;
set SERVER_PACK_CLASSPATH=%SERVERPACK_CLASSPATH%;%SERVERPACK_DFC_DATA%dfcbase.jar;
%SERVERPACK_DFC_DATA%All-MB.jar;%SERVERPACK_DFC_DATA%bsf.jar;
set SERVER_PACK_CLASSPATH=%SERVERPACK_CLASSPATH%;
%SERVERPACK_DFC_DATA%log4j.jar;%SERVERPACK_DFC_DATA%xalan.jar;
%SERVERPACK_DFC_DATA%xml-apis.jar;%SERVERPACK_DFC_DATA%workflow.jar;
set SERVER_PACK_CLASSPATH=%SERVERPACK_CLASSPATH%;%SERVERPACK_DFC_DATA%subscription.jar;
%SERVERPACK_DFC_DATA%xforms.jar;
%SERVERPACK_DFC_DATA%bpmutil.jar
rem *****
rem * The following lines offer some detailed configuration based on definitions above.
rem * It should not be necessary to edit these lines in most cases
rem *****
set SERVERPACK_DEBUG_OPTS=-Xdebug -Xrunjdwp:transport=%SERVERPACK_DEBUG_TRANSPORT%,
address=%SERVERPACK_DEBUG_ADDRESS%,server=y,suspend=n
set SERVERPACK_TUNING_OPTS=-Xms256m -Xmx256m -XX:NewSize=64m -XX:MaxNewSize=64m -XX:SurvivorRatio=14 -verbose:gc
set SERVERPACK_LIB_OPTS="-Djava.library.path=%SERVERPACK_PATH%"
set SERVERPACK_APP_OPTS=-Dbuild.compiler.emacs=true
Update the %SERVERPACK_CLASSPATH% in startupServer.bat with the CLASSPATH defined in
catalina.bat, replacing the absolute paths with paths relative to %SERVERPACK_HOME%.
The Java VM options in the server pack are split into %SERVERPACK_DEBUG_OPTS%, %SERVERPACK_TUNING_OPTS%,
and %SERVERPACK_LIB_OPTS%. Update these variables with the options specified in %CATALINA_OPTS% in
catalina.bat
rem ----- The next two lines were added by a Documentum installer - please do not remove this comment -----
set CATALINA_OPTS=%CATALINA_OPTS% -Djava.library.path="C:Program FilesDocumentumshared" -Xms256m -Xmx256m -verbose:gc
set CLASSPATH=C:Program FilesDocumentumshareddfc.jar;C:Program FilesDocumentumsharedbsf.jar;C:Program FilesDocumentumsharedAll-MB.jar;C:Program FilesDocumentumsharedlog4j.jar;C:Program FilesDocumentumsharedxalan.jar;C:Program FilesDocumentumsharedxml-apis.jar;C:Program FilesDocumentumsharedworkflow.jar;C:Program FilesDocumentumsharedsubscription.jar;C:Program FilesDocumentumsharedxforms.jar;C:Program FilesDocumentumsharedci.jar;C:Program FilesDocumentumsharedadmin.jar;C:Program FilesDocumentumsharedbpmutil.jar;C:Documentumconfig;%CLASSPATH%

Step 12: Configure DFC

dfc.properties

dfc.properties contains the fully qualified path to the %DFC_DATA% directory. As this path
must be fully qualified (i.e. C:/WebtopServerPack5.2.5sp2/dfc) it is not portable. This is the
only “hard coded” path in a server pack. When deploying a new instance of the server pack (either on the same
machine or another machine) it is important to remember to update this path with the path to the new instance.

Note:
dfc.properties is a Java properties file. In Java properties files, the back slash is an
escape character so the path must use either forward slashes or double backslashes ().

dmcl.ini

It is often useful to have a server pack specific dmcl.ini file. The startServer.bat script defines
DMCL_CONFIG referencing a dmcl.ini file in the root of the server pack. This line
is commented out in the sample script which causes the dmcl.ini file to be loaded from the default
location (%SYSTEMROOT%dmcl.ini). Copy your dmcl.ini file into the server pack root
and uncomment the DMCL_CONFIG line in startServer.bat

BOF

The Business Objects Framework provides a means of extending the functionality provided by DFC. BOF classes need
to be loaded by the same classloader which loads DFC. For this reason, BOF classes can not be installed as part
of a web application (i.e. in WEB-INF/lib or WEB-INF/classes) as web applications
are loaded by a classloader specific to that web application.

At Blue Fish, we have found it useful to create a separate directory in our server packs for BOF classes.
For our example environment, we created %SERVERPACK_HOME%bof. You will notice that the
sample %SERVERPACK_CLASSPATH% contains a reference to %SERVERPACK_BOF_HOME%sampleBofTypes.jar.
Any JAR files containing BOF classes will need to be included in the classpath.

Note:
You may need to include an explicit reference to servlet.jar in the classpath if BOF classes or classes
referenced by the BOF classes reference the servlet API.

Final Directory Structure

You should now have a complete server pack. The directory structure should look something like the figure below.

Figure 7:
Server Pack Directory Structure (Click to Enlarge)

References

startServer.bat

The sample startup script for Tomcat 4 on Windows. Download.

VMWare

Software for running virtual machines. This is useful for the “clean” environment needed to create a server pack.
VMWare website.

Firedaemon

The startup script provided is a batch file. This is fine for most developers. Some developers, however, would prefer
to run their servers as Windows services. Server Packs are used extensively at Blue Fish and we even run some of our
internal production servers using server packs. Obviously these instances need to run as services.

The utility
FireDaemon
enables any EXE or batch file to run as a service on Windows.
There are a number of similar utilities but the author has had really good success with FireDaemon.
It is very reasonably priced at $29.00. Check out the FireDaemon website.

Conclusion

WDK developer server packs provide a great way for one developer to run multiple WDK server environments on one machine.
They are great for development teams. One developer can configure the server pack, zip it up, and distribute it to the
rest of the team so only one team member has to go through the installation and configuration process.

As we have seen, there is no magic involved in creating a server pack. Each organization will likely want to create a slightly different
flavor of server pack. The sample environment we walked through is similar to the server packs that we build at Blue Fish and have used
on many projects over the last couple of years. Hopefully, it provides a useful starting point for constructing server packs for your
organization.