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
WDK developer server packs (refered to in this article simply as
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.
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:
- Application server (eg. Tomcat)
- 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
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.
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
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
Step 6: Poach the JDK/JRE
Copy the entire JDK directory
C:j2sdk1.4.1_07 into the server pack directory creating the directory
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
Step 8: Poach the Tomcat Install
Copy the tomcat directory (which no longer contains the webtop web application) to the sever pack directory creating
Step 9: Poach the DFC Install
Create a directory for the DFC install in the server pack directory. We’ll create
There are three sets of files which need to be copied to collect the DFC installation.
- 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
win32directory and leave it at that.
Copy the DLLs from
- The next set is the JAR files necessary for DFC. Copy the JAR files from
- The final set is the config directory containing the
dbor.properties. In our sample installation, this is located at
Copy this directory to the top level of our server pack directory creating
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
to the tomcat
server.xml file. Edit
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.
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 * 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 *** A server pack-specific dmcl.ini is often useful
rem set DMCL_CONFIG=%SERVERPACK_HOME%dmcl.ini
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 * The following lines offer some detailed configuration based on definitions above.
rem * It should not be necessary to edit these lines in most cases
set SERVERPACK_DEBUG_OPTS=-Xdebug -Xrunjdwp:transport=%SERVERPACK_DEBUG_TRANSPORT%,
set SERVERPACK_TUNING_OPTS=-Xms256m -Xmx256m -XX:NewSize=64m -XX:MaxNewSize=64m -XX:SurvivorRatio=14 -verbose:gc
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
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 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.
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 (
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
%SYSTEMROOT%dmcl.ini). Copy your
dmcl.ini file into the server pack root
and uncomment the
DMCL_CONFIG line in
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/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
%SERVERPACK_CLASSPATH% contains a reference to
Any JAR files containing BOF classes will need to be included in the classpath.
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.
The sample startup script for Tomcat 4 on Windows. Download.
Software for running virtual machines. This is useful for the “clean” environment needed to create a server pack.
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.
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.
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