# How to install Apache JServ on UNIX systems

### Requirements

The following requirements exist for building Apache JServ:

- 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.

- Apache HTTP Server

  Apache JServ 1.1 works only with the Apache HTTP Server (only version 1.3.x is supported).

- Java Runtime Environment

  A fully compliant Java 1.1 or greater Runtime Environment is required for Apache JServ to execute. The official list of compatible ports is found on Sun's Java web site. The list of supported platforms and Java ports can be found here.

  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 it to your Java virtual machine implementers.

- Java Servlet Development Kit 2.0

  The JavaSoft JSDK 2.0 is required by Apache JServ for proper servlet execution. This package is freely available from Sun's Java Servlet web site

  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.

- Java Compiler

  Any compiler compatible with the Java 1.1 or greater specification. A list of supported Java compilers may be found here.

  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.

- 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/

- 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.

### Choose how to add the Apache JServ module to Apache

There are two choices:

- Compile it in - 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.
- DSO - This requires that you have an installation of Apache 1.3.* that was configured to have DSO support when it was built. If you're not sure whether your has DSO support, follow the instructions on configuring Apache JServ for DSO and the configure script will tell you.

### 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`

### 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.

- 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`

  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.

- 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

- 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`

- 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`

- Support for EAPI (mod_ssl)

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

  > `--enable-EAPI`

- Examples

  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`

### 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 install`

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

### 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

### 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/

Copyright (c) 1997-99 The Java Apache Project.
$Id: howto.unix_install.html,v 1.9 1999/12/10 23:25:45 admin Exp $
All rights reserved.