Apache-Tomcat 4.1 for Debian
============================

- The home directory (CATALINA_HOME) for Tomcat 4.1 (a.k.a. Catalina) is
  /usr/share/tomcat4, the base directory (CATALINA_BASE) is /var/lib/tomcat4
  but some files in there are just symlinks to the proper FHS directories.

  There's a .debian directory in /usr/share/tomcat4 which contains templates
  for configuration files. These are copied to the conf direcory during
  the package installation when the corresponding destination does not yet
  exist.

- The package has been built as "light" distribution which means that some
  of the additional features like JavaMail, JTA and Tyrex are not enabled.
  Catalina was compiled using MX4J so JMX is available for an embedded
  servlet engine.

- The main configuration file is /etc/tomcat4/server.xml.
  The default setup enables the built-in HTTP web server on port 8180 and
  a Coyote/JK2 AJP 1.3 connector for Apache on port 8009. The standard port
  8080 for the web server was not used so the package does not conflict with
  junkbuster. Tomcat also listens on port 8005 (localhost only) for a
  shutdown command.

- Tomcat 4.1 needs a full Java Development Kit (JDK); a Java Runtime
  Environment (JRE) is not sufficient because javac is needed for translating
  JavaServer Pages (JSP) into Java classes.
  The java-package utility enables the creation of a Debian package 
  for your JDK, so that dependencies are appropriately handled.  This is
  recommended over manual installation of a JDK; see the java-package 
  documentation for details.

- You can install your own web applications as .war files or in extracted form
  into a subdirectory of /var/lib/tomcat4/webapps. The name of the WAR file
  or subdirectory is the servlet context for this webapp.

- You can test if Tomcat is working properly by pointing your favorite web
  browser to http://localhost:8180/ and testing some of the Servlet and JSP
  examples. This requires installation of the tomcat4-webapps package.

- Multiple Tomcat instances can be started by different users when
  $CALALINA_BASE is set to a local directory that contains the subdirectories
  conf, logs, webapps, work and temp. See RUNNING.txt for more about this.

- Tomcat is started using a security manager, you can define the permissions
  for your servlets and JSPs in /etc/tomcat4/policy.d/*. All files in this
  directory are joined to /etc/tomcat4/catalina.policy.

  If your webapp does not work with the tomcat4 Debian package but works fine
  with the binary distribution from Jakarta, try to disbale the security
  manager in /etc/default/tomcat4 first. If this works, add the required
  permissions in a new file in /etc/tomcat4/policy.d/ and re-enable the
  security manager.

  Disabling the security manager is not recommended on production systems
  since a call to System.exit() in a servlet of JSP page would then stop the
  whole virtual machine that is running Tomcat.

- There is a webapp for basic web-based administration of Tomcat's webapps
  in the tomcat4-admin package. You need to add one of the users in
  /var/lib/tomcat4/conf/tomcat-users.xml to the manager role and probably
  set a better password. The "Web Application Manager" can then be accessed
  at http://localhost:8180/manager/html. There's also a more sophisticated
  administration webapp called "admin" in the same package but it can't make
  permanent changes to the configuration since the tomcat4 user does not have
  permission to do this in the default configuration.

- Tomcat 4.1 does not follow symlinks by default. You can change this by adding
  this section to your webapp's context definition:

  <!-- make symlinks work in Tomcat 4.1 -->
  <Resources className="org.apache.naming.resources.FileDirContext"
             allowLinking="true" />

  See /etc/tomcat4/server.xml or /var/lib/tomcat4/webapps/admin.xml in the
  Debian package tomcat4-admin for examples.

- For more information about Jakarta-Tomcat please take a look at the Tomcat
  home page at http://jakarta.apache.org/tomcat/index.html.

- The official Servlet 2.3 and JSP 1.2 specifications can be found at
  http://java.sun.com/products/servlet/ and http://java.sun.com/products/jsp/

