+-------------------------------------------------------------------+
   | A P A C H E   J S E R V   I N S T A L L A T I O N   O N   U N I X |
   +-------------------------------------------------------------------+


  Introduction
  ============

  This file guides you through the installation process for UNIX systems.

  NOTE: Win32 users are highly recommended to use the self-installing 
  distribution (the "exe" distribution) or read the instructions 
  in the docs/install/ directory.


  Installing the Apache JServ servlet engine
  ==========================================

  1. Requirements
     ------------

     The following requirements exist for building Apache JServ:

     o  Disk Space: 
     
        The complete Apache JServ installation requires less than 2Mb of 
        hard disk space. The compiled, not-compressed jar archive is more or
        less 100Kb.

     o  Apache HTTP Server:
    
        We have removed all support for Apache 1.2.x. Apache 1.3.9 and 
        higher is the current supported version. Apache 1.3.9 has 
        been out for quite some time now and we feel that it is best that 
        you always upgrade to the latest version of Apache. We also had 
        several bugs as a result of bugs in Apache 1.2.x that have been 
        resolved in Apache 1.3.9.

     o  Java Runtime Environment:
  
        A fully compliant Java 1.1 Runtime Environment is required for Apache 
        JServ to execute. 
  
        The official list of compatible ports is found on the Sun Java 
        web site:

        <http://java.sun.com/cgi-bin/java-ports.cgi>
  
        The list of supported platforms and Java ports may be found in the 
        documentation (docs/support.html).
  
        NOTE: since Apache JServ uses _only_ standard Java APIs (java.*),       
        please, do not submit a bug report if your Java virtual machine fails 
        to execute Apache JServ because of broken compliance. Send the 
        bug report to your Java virtual machine implementors instead.
  
     o  Java Servlet Development Kit 2.0:
  
        The Sun Java JSDK 2.0 is required by Apache JServ for proper servlet 
        execution.  This package is freely available from the Sun Java web 
        site: 

        <http://java.sun.com/products/servlet/index.html>
        <http://java.sun.com/products/servlet/download.html>

        NOTE: this version of Apache JServ requires _EXACTLY_ the 2.0
        version of the JSDK in order to operate properly. Any other version
        (past, present or future and including the version that comes 
        with the Java Server Pages (JSP) jar file) is not supported.
        
     o  Java Compiler:
  
        Since most distributions include the precompiled Java binary archive,
        compilation of the Java source is optional.
        
        A list of supported Java compilers and virtual machines may be found 
        in the documentation (docs/support.html)
        
        NOTE: to build servlets, a Java compiler is needed. The Jikes compiler
        from IBM is a fast and easy to use replacement for Sun's slower javac 
        compiler. <http://www.alphaworks.ibm.com/tech/jikes>

     o  ANSI-C Compiler: 

        Make sure you have an ANSI-C compiler installed and relative Make 
        tools. The GNU C compiler (GCC version 2.7.2 is fine) or the EGCS C 
        compiler (the future of the GCC compiler) and GNU Make 
        (make preferably version 3.75) from the Free Software Foundation (FSF) 
        is recommended. If you don't have GCC then at least make sure your
        vendors compiler is ANSI compliant. You can find the homepage of GNU
        at <http://www.gnu.org/> and the GCC distribution under
        <http://www.gnu.org/order/ftp.html>. EGCS is available from 
        <http://egcs.cygnus.com/>.

     o  Dynamic Shared Object (DSO) support [OPTIONAL]:

        See your Apache documentation for more information on how to add
        DSO support and if your system is supported. You will need to make 
        sure that Perl 5.004 or later is installed in order to build DSO 
        modules because of the dependency on the Apache apxs module. 
        <http://www.perl.com/>


  2. Choose how to add the Apache JServ module to Apache
     ---------------------------------------------------

  There are two choices:
    
     o  Compile it in -  This requires that you have a source distribution 
        of the Apache server handy as it adds our source to that tree and 
        lets Apache build the Apache JServ module into itself statically.    
 
     o  DSO - This requires that you have an installation of Apache 1.3.9 
        or higher that was configured to have DSO support when it was 
        built.  If you are not sure whether your server has DSO support, 
        follow the instructions on configuring Apache JServ for DSO and the 
        configure script will tell you.


  3. Configure Apache First - IMPORTANT
     ----------------------------------

  If you are using a source distribution then you have to configure Apache
  first (some generated header files are needed for Apache JServ to pass its
  configure checks).  You do not need to worry about specifying the 
  Apache JServ module for this first run.

  Thus, a first time configure line to build a static version of Apache
  would look like this:

  ./configure \
       --prefix=/usr/local/apache
  make install

  If you are using DSO then you can ignore this step.  If you have a source
  distribution and would like to build it with DSO support and install it
  for use by Apache JServ then use the following options when configuring
  Apache:

     --enable-rule=SHARED_CORE --enable-module=so
     
  Thus, a first time configure line to build a DSO version of Apache
  would look like this:

  ./configure \
       --prefix=/usr/local/apache \
       --enable-rule=SHARED_CORE \
       --enable-module=so
  make install


  4. Configure Apache JServ
     ----------------------

  Now you are ready to configure Apache JServ.  To do this you may (or may not)
  need to specify quite a few arguments to configure.  The options to 
  pass to Apache JServ's configure are described below with complete 
  examples at the very bottom of this section.

  o  Apache Directory

     For DSO use:

       --with-apxs=/path/to/apache/installation/bin/apxs

     NOTE: The configure script will check a the default installation
     directory, /usr/local/apache. If you have Apache already installed 
     in there, you may leave this argument out.

     For a static compile use:

       --with-apache-src=/path/to/apache/source

     This is the path to the top level Apache directory from the source  
     distribution. In other words, this should point to the directory 
     that *contains* the src directory.

     NOTE: Do not try to use both --with-apxs and --with-apache-src 
     options at the same time. Also, Apache JServ 1.0, used 
     --with-apache-install. This has been deprecated and you should now use 
     --with-apxs instead.

  o  Prefix Path

     'make install' will copy the documentation and Apache JServ .jar file 
     into the directory that you specify with this option:

       --prefix=/usr/local/jserv

     The default value for this option is /usr/local/jserv

  o  JDK programs (java, javac, javadoc and jar)

     By default configure will first look at the JDK_HOME and JAVA_HOME 
     environment variables, if they aren't set then configure will check 
     your PATH environment variable. The results from using the PATH can 
     be overriden by:

       --with-jdk-home=/path/to/jdk

     If they are not found, configure will tell you and default back to 
     whatever is in your PATH.

     It is also possible to specify the locations of the java binaries 
     and force Java 2 usage with the following options:

       --with-java-platform=1 or 2 (generally no need to specify this)
       --with-java=/path/to/binary/java
       --with-javac=/path/to/binary/javac
       --with-javadoc=/path/to/binary/javadoc
       --with-jar=/path/to/binary/jar

     NOTE: By default, debugging symbols are left out of the Apache JServ 
     classes, you can put them back in by using this option:

       --enable-debugging

     NOTE: By default the jar file is not compressed, this can be 
     changed like so:
 
       --enable-compressed-jar

  o  JSDK classes

     Apache JServ needs to know where your servlet classes are.
     You will need to specify them like so:

       --with-JSDK=/path/to/jsdk.jar
          or
       --with-JSDK=/path/to/unpacked/jsdk

  o  Support for EAPI (mod_ssl)

     If you are using mod_ssl, then you should enable EAPI support by 
     adding:

       --enable-EAPI


  An example configure line for STATIC compilation is:
  
        ./configure \
                --prefix=/usr/local/jserv \
                --with-apache-src=/usr/local/apache/source \
                --with-jdk-home=/path/to/jdk \
                --with-JSDK=/path/to/jsdk.jar \
                --disable-debugging

  An example configure line for DSO compilation is:
  
        ./configure \
                --prefix=/usr/local/jserv \
                --with-apxs=/usr/local/apache/bin/apxs \
                --with-jdk-home=/path/to/jdk \
                --with-JSDK=/path/to/jsdk.jar \
                --disable-debugging


  5. Build Apache and Apache JServ
     -----------------------------

  Once you have configured Apache JServ you can run make. 

  Run 'make install' to make a .jar file, and copy it and the docs into 
  the directory you specified as --prefix. If you are building the DSO 
  version, this will compile the shared object. If you are building the 
  static version, this will just build the Java classes.

  If you are using an Apache source distribution then you also have 
  to run 'make install' in the Apache source directory to build Apache 
  with Apache JServ support in it. To do this, you will need to add the 
  following line to the static configure line in section 3 above:

    --activate-module=src/modules/jserv/libjserv.a

  This is an example of building a default Apache installation with 
  Apache JServ support added:

    ./configure \
        --prefix=/usr/local/apache
        --activate-module=src/modules/jserv/libjserv.a
    make
    make install

  You can see if Apache has loaded the mod_jserv module by executing 
  '/path/to/apache/installation/bin/httpd -l'.
  

  6. Configuration Files
     -------------------

  At this point, you must configure the Apache JServ directives for Apache. 
  There are example configuration files in the conf and example directories 
  that come with the Apache JServ package that help with this process. The 
  files in the example directory will help you configure a default zone 
  named "example" so that your URL's will look like this:
  
  <http://www.yourserver.com/example/Hello>

  There are three different types of configuration files for Apache JServ, 
  the first one should be included in your httpd.conf file with the Apache 
  "Include" directive. For example, in your httpd.conf file, you should have 
  a line like this: "Include /path/to/jserv.conf". 
  
  Within your "jserv.conf" file, there is a line that gives the path to the 
  second type of configuration file, the "jserv.properties" file. The line 
  in the jserv.conf file looks like this: "ApJServProperties 
  /path/to/jserv.properties".
  
  Lastly, within the "jserv.properties" file is a line that points to your 
  zone configuration file. If you have a zone called "example", then you 
  will need to have an "example.properties" file and the location to this 
  file is then defined with this line in your "jserv.properties" file: 
  "example.properties=/path/to/file/example.properties"

  Thus, the configuration file path looks like this:

  "->" sounds like "points to"

  httpd.conf -> jserv.conf -> jserv.properties -> example.properties
  
  You should make sure to edit all of these files and fill in the 
  appropriate information according to the comments provided in each of the 
  files. If you have questions about the definitions, you should consult 
  section 8 below, the documentation in the docs directory, on the 
  website, FAQ-O-Matic and/or the Java Apache Users mailing list.

  <http://java.apache.org/jserv/>
  <http://java.apache.org/faq/>
  <http://java.apache.org/main/mail.html>

  7. Problems
     --------

  First, look in the various log files for errors. If you are not getting 
  log files created, then this is generally a result of incorrect 
  permissions on the log files. Make sure that the user (ie: nobody) that 
  the Apache httpd is running as can write to the log files.

  Next, read the FAQ-O-Matic and documentation to see if your issues  
  have already been covered (there is a good chance that they have been). 
  
  <http://java.apache.org/faq/>
  
  Configuration errors and questions are not considered bugs and those 
  should be directed to the Java Apache Users mailing list.

  <http://java.apache.org/main/mail.html>

  If think that you have found a bug, please report it to the Apache Bug 
  Database at: 

  <http://bugs.apache.org/>


  Enjoy!

  -The Apache JServ Project