WebMan: A Basic RefEntry Servlet
<<< PreviousNext >>>

Installing the Application

This chapter describes how to install the project software both on Linux and on Windows systems.

Installing on Linux

This seems to work on Solaris systems and possibly other UNIX systems as well. The examples in the following steps work if you are running Bash, the default shell on Linux. To run Bash in a terminal window, enter bash at the shell prompt.

  1. Make sure you have a Java Development Kit 1.4 or later installed. If you do not have a recent JDK, download one from http://java.sun.com. If you do not know which version you have, then check. For example, if you have installed 1.4.1:

    bash$ java -version
java version "1.4.1-rc"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-rc-b19)
Java HotSpot(TM) Client VM (build 1.4.1-rc-b19, mixed mode)

  2. Do not begin the installation before reading this:

    The only pack you must install is the servlet .war file. This is the case so you do not have to reinstall Ant, HttpUnit, or Tomcat if you have it already.

    If you want to use the servlet .war file, you must have a servlet container such as Tomcat. So if you are missing a servlet container, install the Tomcat pack at least.

    If you want to do any development, such as write your own RefEntry documents and build a servlet, then you need Ant and HttpUnit. Unless you have Ant and HttpUnit already installed, take these packs as well.

    If you are reading this file, you may have already decided to install the documentation. Good.

  3. Run the self-extracting installer, refentry-installer.jar.

    bash$ java -jar install-dir/refentry-installer.jar

    Follow the instructions based on what you decided to install.

    If you run this in a terminal without starting X, the installer generates an unexpected exception on startup and exits, displaying the stack trace. This particular installer does not work without a GUI, so start X before you run it. You can go back to your terminal window after you install it.

  4. Set JAVA_HOME to point to the JDK if it is not set already. For example:

    bash$ echo $JAVA_HOME

$ which java
path-to-java/bin/java
$ export JAVA_HOME=path-to-java

    If you are on a network where multiple Java SDK versions are maintained side by side, finding the JAVA_HOME might be much less straightforward. At work, one of my install testers had to follow three symbolic links before she finally got to the directory where Java was actually physically installed.

  5. Source the refentry.profile file in the directory where you installed the bits. For example:

    bash$ source install-dir/refentry.profile

    The refentry.profile file is written for Bash. Hack the file yourself if you want to use a different shell.

  6. Copy the servlet .war file to the Tomcat webapps directory.

    bash$ cp install-dir/refentry.war $CATALINA_HOME/webapps/

    CATALINA_HOME designates the Tomcat servlet container installation directory.

  7. Start the Tomcat servlet container.

    bash$ $CATALINA_HOME/bin/startup.sh

    This starts the Tomcat servlet container in the background.

  8. Browse http://localhost:8080/refentry and you should see the default page of the RefEntry servlet.

If everything went well and you want to develop your own RefEntry servlet with your own documentation, you might want to add two lines in your .bash_profile to set JAVA_HOME and to source refentry.profile at startup.

If you want to stop Tomcat, the command is: $CATALINA_HOME/bin/shutdown.sh

<<< PreviousHomeNext >>>
In this Document Installing on Windows