WDK Developer Server Packs

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.5sp2\j2sdk1.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%\webapps\webtop becomes C:\WebtopServerPack5.2.5sp2\webtop

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.5sp2\jakarta-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.5sp2\dfc.

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.5sp2\dfc\win32. 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 Files\Documentum\Shared to C:\WebtopServerPack5.2.5sp2\dfc\win32.
2. The next set is the JAR files necessary for DFC. Copy the JAR files from C:\Program Files\Documentum\Shared to C:\WebtopServerPack5.2.5sp2\dfc.
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:\Documentum\config. Copy this directory to the top level of our server pack directory creating C:\WebtopServerPack5.2.5sp2\config

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.5sp2\jakarta-tomcat-4.1.27\conf\server.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 Files\Documentum\shared" -Xms256m -Xmx256m -verbose:gc
set CLASSPATH=C:\Program Files\Documentum\shared\dfc.jar;C:\Program Files\Documentum\shared\bsf.jar;C:\Program Files\Documentum\shared\All-MB.jar;C:\Program Files\Documentum\shared\log4j.jar;C:\Program Files\Documentum\shared\xalan.jar;C:\Program Files\Documentum\shared\xml-apis.jar;C:\Program Files\Documentum\shared\workflow.jar;C:\Program Files\Documentum\shared\subscription.jar;C:\Program Files\Documentum\shared\xforms.jar;C:\Program Files\Documentum\shared\ci.jar;C:\Program Files\Documentum\shared\admin.jar;C:\Program Files\Documentum\shared\bpmutil.jar;C:\Documentum\config;%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.

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.