Enhydra Multiserver on NT Server 4.0

by Tori Harris,
Epic Partners, Inc.

The purpose of this document is to provide general information for use when setting up production servers (web and application). This document does not attempt to provide detailed instructions for building the servers. Instead, the intention is to supplement existing documentation with specific, timesaving information. Where possible, references to the full documentation are provided in this document. It is critical to read and understand the vendor-provided documentation first, then return to this document for specifics pertaining your production environment.

Installing Java on the Web/Application Server:

Relevant Documentation: Java 2 SDK readme file (C:\jdk1.2.2)

The installation of Sun's Java Software Development Kit (SDK) is very straightforward as of version 1.2.2. Note that this document was writen with version 1.2.2_005. Also note that there are currently problems with version 1.3 that prevent it from being used with "Serve Anything" as an NT service.

The following general steps should be used as a guideline for installing the SDK.

  1. Create a new directory on the web server called "Install."

  2. Download the Java 2 SDK v 1.2.2_005 Windows 95/98/NT Production Release (Intel Platform) from http://java.sun.com/products/jdk/1.2/ to the Install directory. Note: Select the "One large bundle (~20MB)" version.

  3. Run the self-extracting .exe file and follow the directions.

  4. Accept the default (C:\jdk1.2.2) installation directory.

  5. On the "Select Components" screen, you may omit both "Demos" and "Java Sources."

  6. Accept the default (C:\Program Files\JavaSoft\JRE\1.2) directory for the Java Runtime Environment (JRE).

 

Installing Enhydra on the Web/Application Server:

Relevant Documentation: "Getting Started with Lutris Enhydra"

(http://www.enhydra.org/software/documentation/enhydra/index.html)

Lutris has greatly simplified and improved the installation process for Enhydra with version 3.0. This document was written with version 3.0.1.

The following general steps should be used as a guideline for installing Enhydra.

  1. Download the "InstallShield" version of Enhydra 3.0.1 under "Enhydra for Windows" at http://www.enhydra.org/software/enhydra/downloads/index.html to the Install directory. Note: Be sure to select the "Enhydra3.0.1.exe 30.9 meg" version.

  2. Run the self-extracting .exe file and follow the directions.

  3. Accept the JDK version detected at C:\jdk1.2.2.

  4. Accept the default (C:\usr\local) location for Enhydra Packages.

  5. On the "Setup Type" screen, select "Custom."

  6. On the "Select Components" screen, you may omit both "Enhydra Source" and "Enhydra Demos Source."

  7. Once the installation is complete, open the ".bashrc" file under C:\enhydra (Wordpad works well for this purpose).

  8. Edit the path statement to include the correct information for the Enhydra installation and save the file.

    For example, change the default path from:

    PATH=/bin:/usr/local/bin:/usr/local/enhydra/bin:$PATH

    to:

    PATH=/bin:/usr/local/bin:/usr/local/enhydra3.0.1/bin:$PATH

  9. Run Cygnus Tools (use the "Enhydra Shell" icon, now on the desktop).

  10. Type cd /usr/local/enhydra3.0.1
  11. Type ./configure /jdk1.2.2 (this edits several files to set the enhydra installation location)
  12. To confirm a successful Enhydra installation, create a simple application as follows. . .
  13. Type cd /usr/local
  14. Type mkdir project
  15. Type cd project (you should now be in the /usr/local/project directory, use pwd to confirm)
  16. Type newapp myapp (this should create a simple application called "myapp")
  17. Type cd myapp
  18. Type make (this should compile the application and generate all files required to run)
  19. Type cd output
  20. Type ./start (this will run the application)
  21. On the console screen (DOS window), note the port the application is "listening" on (default is 9000).
  22. Open your browser and confirm the application is running correctly at http://127.0.0.1:9000
  23. Press CTRL+C within the console window to stop the application.

Configuring Enhydra Multiserver to Run as an NT Service:

Relevant Documentation: srvany.doc

The "Serve Anything" (srvany) application included with the NT Resource Kit allows us to run the Enhydra Multiserver as an NT service. This arrangement is advantageous since the service will continue to run when a user logs on or off, will restart when the server restarts (if configured to do so), and can be monitored by various third party applications. The Srvany.doc file included with the application does a reasonably good job of describing the process required to install and run an application as a service. Note that it will be necessary to know the permanent location of the Srvany.exe file prior to installation.

Since we are running Enhydra Multiserver, which is nothing more than a Java application, we must supply all required parameters for running the application. In general, we must provide the exact same information as if we were running the application from a command prompt.

Note: Use extreme caution when editing the NT registry. An error may cause unpredictable results, including the requirement for a complete server rebuild.

The following is an Enhydra Multiserver-specific summary of the installation documentation for Serve Anything. Please review the "Srvany.doc" document before attempting an installation of the Enhydra service. These instructions assume that Enhydra is installed and functioning on your server and that you have a copy of Serve Anything from the NT 4.0 Resource Kit.

  1. Copy the srvany.exe, srvany.doc, and instsrv.exe files from the Resource Kit to the c:\enhydra directory on your NT server.

  2. At the command prompt, change to the c:\enhydra directory and type

    instsrv Enhydra c:\enhydra\srvany.exe

    This will install the Enhydra service, which can then be accessed using the Service Control Manager applet (under control panel - services). Before the service will actually do anything, however, you must edit the NT registry.

  3. At the command prompt, type regedt32

    The Enhydra service is located under:

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Enhydra\

  4. With the Enhydra service selected:

    Under the "Edit" Menu, select "Add Key"

    Key Name: Parameters

    Class: REG_SZ

  5. Select the New Parameters Subkey

    Under the "Edit" Menu, select "Add Value"

    Value Name: AppDirectory

    Data Type: REG_SZ (should already be filled in)

    String: "c:\enhydra\"

  6. Repeat the previous step with the following values:

    Value Name: Application

    Data Type: REG_SZ (should already be filled in)

    String: "c:\jdk1.2.2\bin\java.exe" (be sure this matches the path to your java.exe file)

    Value Name: AppParameters

    Data Type: REG_SZ (should already be filled in)

    String:

    -cp "c:\usr\local\enhydra3.0.1\lib\enhydra.jar;c:\jdk1.2.2\lib\inetJDBC.zip;c:\jdk1.2.2\lib\Signio.jar;c:\jdk1.2.2\lib\epic.jar;%CLASSPATH%;c:\jdk1.2.2\lib\tools.jar" "com.lutris.multiServer.MultiServer" "c:\usr\local\enhydra3.0.1\multiserver.conf"

    Note: You must ensure that the parameters match settings and file locations on your server. It may be possible to simplify the AppParamters string for some installations. The general format of the string is:

    -cp classpath mainclass arguments

    Type java at the command prompt for a full explanation. Here, we have included the full classpath (after the "-cp" switch) followed by the fully qualified class name, with the path to the multiserver.conf file as an argument.

  7. When these steps are complete, you should see something similar to the following under the Parameters subkey.

  8. Close the Registry Editor.

  9. Under the Service Control Manager applet (Control Panel - Services), select the newly created Enhydra service and select "Startup. . .". Select the appropriate Startup Type (Automatic for most production installations). You may also allow the service to interact with the desktop if you would like to see a console output of what is going on behind the scenes with the service.

     

    Note: If you select "Allow Service to Interact with Desktop," you should expect to see a Java thread dump at the console when logging off the server. This should occur without any errors and does not appear to cause any problems with Java or Enhydra. When logging off the machine, the service will continue to run and the console window will still be visible once the user logs back into the server.

    In addition, do not manually close the console window to kill the Enhydra service as this will cause a number of errors and will place the Multiserver in an unstable condition. To close the console window, use the Services applet to stop the Enhydra service (the console window will close automatically). Except for troubleshooting purposes, allowing the service to interact with the desktop is not recommended. . .especially in a production environment.

  10. Once you have confirmed all the above settings, restart the server and confirm the automatic startup of the Enhydra Multiserver.

 

Configuring Enhydra Director:

Relevant Documentation: "Using Enhydra Director"

(http://www.enhydra.org/software/documentation/enhydra/index.html)

The Lutris documentation for using Enhydra Director with IIS is very thorough. Follow the directions closely to avoid problems with the www service on the server. Note that the enhydra_director.conf file contains a significant amount of commented information that describes how the file should be configured. Pay careful attention to the example configurations within the file. Although the instructions are "commented out," the code is not. . .but should be before being placed into production! Comment out all code that does not pertain to your configuration. When restarting the web server, delays of more than 2 minutes are a good indication that the enhydra_director.conf file contains uncommented, bogus configuration information. If this is the case, Enhydra Director will force IIS to execute DNS queries based on the examples in the file. Each query takes about 2 minutes to time out, causing delays of 5 - 10 minutes for the server to fully start.

 

Adding an Enhydra Application with the Multiserver Admin Console:

Relevant Documentation: "Getting Started with Lutris Enhydra" (http://www.enhydra.org/software/documentation/enhydra/index.html).

The "Installing Enhydra on the Web/Application Server" section discussed running a simple Enhydra application from the command line. On a production server, however, applications are started with the Enhydra Multiserver Administration Console. The console is a browser-based tool that provides a simplified method of adding and managing Enhydra applications. Once Multiserver is running as a service on the server (see the "Configuring Enhydra Multiserver to Run as an NT Service" section of this document) the console application is available to begin managing your applications. The following steps or normally required only once for each new Enhydra application installed on the server. To allow the Multiserver Console to run the new application, complete the first 10 steps in the "Placing an Application on the Enhydra Multiserver" section before completing the steps below.

  1. Point your browser to http://127.0.0.1:8001. Note that the application runs on port 8001 by default. This setting can be changed by editing the c:\usr\local\enhydra3.0.1\multiserver.conf file.

  2. You will be prompted for a username and password. The defaults are username = admin and password = enhydra. This information can be changed by editing the file at c:\usr\local\enhydra3.0.1\apps\multiserverAdmin.conf.

  3. Click the "Add" button on the left panel to open the "Add New Application/Servlet" window.

  4. You should see the name of your Enhydra application in the "Select Application" dropdown box.

  5. Add a brief description, if desired, and click "OK."

  6. You should see a message indicated the application was added successfully.

  7. Click "OK."

  8. Click on the "Connections" tab at the top of the status window.

  9. Click "create" to add a connection to your application.

  10. You may select "Enhydra Director" to specify a connection between the web server (running Enhydra Director) and Multiserver, or "http" to specify a direct connection between a browser and your application (this option uses Multiserver as a web server). Details for this selection are available in "Getting Started with Enhydra" as well as the "Using Enhydra Director" documents. In either case, you must supply a port and URL prefix in the fields provided. If you are using Enhydra Director, note that the information you provide here must be identical to the corresponding entries in the enhydra_director.conf file.

  11. Click "OK."

  12. You should see a message indicated the connection was added successfully.

  13. Click "OK."

  14. Click on the "Application" tab at the top of the status window.

  15. Note that your application now appears in the "Applications:" window in the upper left corner.

  16. Select your application and note the application status window on the right.

  17. Click the "Start" button on the left panel to start your application.

  18. The status window should indicate that your application is running.

  19. Test your application by pointing your browser at the appropriate address, port, and URL prefix (if applicable). If you are unsure of the URL, click again on the "Connections" tab at the top of the status window. The connection you added previously should show the URL for your application. Note, however, that this URL may be based on a netbios machine name, which is not accessible via the Internet. You can replace everything in the URL up to the colon (before the port number) with the IP address of the server, or a registered DNS server name to access the server over the Internet.

  20. Click the "Save State" button on the left panel to save the changes you have made.

  21. For performance reasons, you should now stop any other running applications listed in the "Applications" window in the upper left corner. Do this by selecting each application and then clicking the "Stop" button on the left panel.

  22. Once again, click the "Save State" button on the left panel to save the changes you have made and confirm that the appropriate applications are either running or stopped, as desired.

  23. You may simply close the browser window when you have completed your configuration changes.

 

Placing an Application on the Enhydra Multiserver:

Relevant Documentation: "Getting Started with Lutris Enhydra" (http://www.enhydra.org/software/documentation/enhydra/index.html).

This is likely the most common procedure undertaken by developers on the server (both in the lab and in production). Here, we assume that the server is already fully configured and running Enhydra Multiserver. In some cases (as it is in the laboratory), Enhydra may be running on the same machine as the web server (IIS). The procedure does not change, but may need to be repeated if there are multiple application servers. Also note that any code ready to be moved to a production server must be fully tested using these procedures in the laboratory prior to being moved into production.

  1. Using the NT Service Control Manager applet, stop the Enhydra service.

  2. Backup all files and subdirectories in the application root directory. For example, for an application named Myapp, the application root directory would be named Myapp, and would contain subdirectories named classes, output, and Myapp (at a minimum). If you cannot find the application root directory, it is often located at c:\usr\local\project\Myapp. This step is most easily accomplished by simply copying the files to an empty temporary directory on the server.

  3. Delete all files in the application root directory.

  4. Copy all new production files and directories into the empty application root directory. Here, you are replacing all the subdirectories and files that were deleted in step 2.

  5. Open the application configuration file (in our example, Myapp.conf) in the output directory. Wordpad works fine and should be available on any NT server.

  6. Edit the Server.ClassPath[] statement to point at the appropriate location on the production server. Ordinarily, this process involves simply commenting out the current statement and "uncommenting" the statement that applies to the production server. If the correct statement is not listed, the syntax should be similar to the following (from our example):

    If running from the Java class files:

    Server.ClassPath[] = c:\usr\local\project\Myapp\classes

    If running from the jar file:

    Server.ClassPath[] = c:\usr\local\project\Myapp\output\lib\Myapp.jar

  7. Save the file and confirm that the original filename was preserved (no .txt extension)

  8. Make a copy of the file and place it in the ENHYDRADIR\apps directory. The EHYDRADIR directory is typically c:\usr\local\enhydra3.0.1 or something similar. This step makes the application configuration file available to the Enhydra Multiserver administration console.

  9. Using the NT Service Control Manager applet, restart the Enhydra service.

  10. Confirm that the Service Control Manager applet indicates that the Enhydra service successfully restarted.

  11. Using a browser, confirm that the application is running and functioning as expected. The Enhydra Multiserver can take up to a minute to restart and begin responding to browser requests.

  12. In the event the application does not respond as expected within 2-3 minutes, stop the service again, copy the backup files back to the application directory, and restart the service. Once again, confirm that the original application is functioning and investigate why the update did not function.