Project:Java/Tomcat 5 Guide

From Gentoo Wiki
Jump to:navigation Jump to:search
The information in this article has been deprecated. It may or may not be relevant for contemporary usage. Handle with care!

This guide provides information on the layout, usage, and other things related to Tomcat version 5.0.28, 5.5.x and later on Gentoo Linux.

Introduction

Some aspects of Tomcat on Gentoo are slightly different than how upstream handles it. This document aims to provide some information on how it differs. This document is based on Tomcat versions 5.0.28, 5.5.x and later. Versions of Tomcat older than 5.5.x should not be used, as it is discouraged by upstream. Which includes Tomcat 5.0.28. Only use that version if your application requires it. Otherwise please use 5.5.x or later when released.

The biggest initial difference on Gentoo is Tomcat being spread across multiple directories. That is because applications on Gentoo strive to comply FHS, in addition to Gentoo-specific standards. Another major differences is that Tomcat is compiled from source, along with the latest versions of any dependencies and bundled libraries, which will also be compiled from source. There are a number of smaller details, which will be covered in this guide.

This document will not cover Java Servlet Specifications, nor general Tomcat configuration. This document assumes the reader has a basic understanding of what a Java Web Application is, consists of, and basics of how to configure a container for the web application.

Layout

Standard Tomcat layout

The root directory of a typical Tomcat binary distribution is laid out as illustrated in the following listing:

/opt/tomcat-x.y/bin
/opt/tomcat-x.y/common
/opt/tomcat-x.y/conf
/opt/tomcat-x.y/logs
/opt/tomcat-x.y/server
/opt/tomcat-x.y/shared
/opt/tomcat-x.y/temp
/opt/tomcat-x.y/webapps
/opt/tomcat-x.y/work
Note
Substitute either 5, or 5.5 for x.y

Gentoo Tomcat layout

To comply with FHS and Gentoo standards, Tomcat has been dissected and installed into the following locations:

/usr/share/tomcat-x.y/bin
/usr/share/tomcat-x.y/common
/etc/tomcat-x.y
/var/log/tomcat-x.y/logs
/usr/share/tomcat-x.y/server
/var/lib/tomcat-x.y/shared
/var/tmp/tomcat-x.y
/var/lib/tomcat-x.y/webapps
/var/run/tomcat-x.y

Configuration files

In addition to simply moving the Tomcat /conf directory under /etc. There is a Gentoo-specific Tomcat configuration file /etc/conf.d/tomcat-x.y, which contains Tomcat variables that are sourced by /etc/init.d/tomcat-x.y. These variables are:

  • JAVA_HOME: default is to be set to $(java-config --jdk-home). Changing this variable allows Tomcat to run with a VM other than the system VM
  • CATALINA_HOME: default is /usr/share/tomcat-x.y
  • CATALINA_BASE: default is /var/lib/tomcat-x.y
  • CATALINA_USER: default is tomcat
  • CATALINA_LIBDIR: default is typically /usr/share/tomcat-x.y/server/lib
  • CLASSPATH: default is ${CATALINA_LIBDIR}
  • CATALINA_TMPDIR: default is /var/tmp/tomcat-*
  • TOMCAT_START: default is "start", with alternatives being "debug", "start -security", "debug -security", or "jpda start"
  • TOMCAT_STOP: default is "stop"
  • CATALINA_OPTS: not set by default , can be used to pass options to Java or Tomcat

The Gentoo init script is also installed into /etc, at /etc/init.d/tomcat-x.y. Tomcat on Gentoo no longer uses or modifies catalina.sh.

Web applications

The /var/lib/tomcat-x.y/ contains a symlinks to other Tomcat directories, and the webapps/ directory where actual web applications go. This directory serves as the hub and is referenced by Tomcat as the CATALINA_BASE.

Gentoo Tomcat base and webapp location:

conf -> /etc/tomcat-x.y
logs -> /var/log/tomcat-x.y
shared
temp -> /var/tmp/tomcat-x.y
webapps
work -> /var/run/tomcat-x.y

Runtime files

These directories hold logs, temp, and working files used by Tomcat.

  • /var/tmp/tomcat-x.y - Tomcat's temporary directory
  • /var/run/tomcat-x.y - Tomcat's working directory, where JSPs Java sources and resulting class files live
  • /var/log/tomcat-x.y - Tomcat's logging directory

Installation

USE flags

Tomcat's USE flags are not any different from USE flags for any package on Gentoo. Most are self-explanatory like doc, sources, and test. They are for documentation, sources, and running unit tests, correspondingly.

The admin USE flag determines if Tomcat's admin webapp will be built and installed. Using this flag also adds struts as a dependency to Tomcat.

The examples USE flag should be used for anyone new to Tomcat, Java Web Application development, or just about anything beyond deploying existing applications. When set, the examples USE flag will install the example web applications. Most all can safely ignore this USE flag, unless you are starting out.

The java5 USE flag will build a Java 1.5 byte code version of Tomcat 5.5.x. It will also reduce a considerable amount of dependencies since mx4j is dropped as a dependency when the java5 USE flag is enabled.

Emerge

Once you have the desired USE flags set in /etc/portage/make.conf or /etc/portage/package.use and added packages names to /etc/portage/package.keywords it's time to actually install Tomcat. Tomcat, like every other package on Gentoo, is installed by doing:

root #emerge --ask www-servers/tomcat
Warning
Because Tomcat is compiled from source, along with all its dependencies, a lot of packages may be pulled in at emerge time. Good news is, since it's Java, aside from download time, should compile rather quickly even on older machines.
Note
Tomcat 5.x versions have allot of questionable dependencies. Tomcat calls them optional core packages. Good news is Tomcat 6.0.x has a fraction of the dependencies of Tomcat 5.x.

Configuration

Depending on what Tomcat will be used for, one may or may not need to finely configure Tomcat. If Tomcat is just a dependency of another application, one might be able to simple start Tomcat, and request the application via a browser or etc at http://127.0.0.1:8080/.

For most others, particularly developers, running more than one site under Tomcat, or etc. will need to edit Tomcat's main configuration file /etc/tomcat-x.y/server.xml. The syntax of that file, and configuration of Tomcat is beyond the scope of this document. Please refer to Tomcat documentation for more information.

Using a specific VM

By default, Tomcat will use the system VM controlled by java-config as-per the JAVA_HOME variable in /etc/conf.d/tomcat-x.y. One can change that variable to point to any VM that is capable of running Tomcat. Then, when Tomcat is started, it will use the specified VM.

Logging

With 5.5.x Logging has changed a bit. Tomcat no longer uses log4j by default. Applications can still use log4j, however the jars have to be put onto the classpath manually. Log4j is not used by a Tomcat install by default, same as upstream. For more information please refer to Tomcat's documentation on logging. Despite this change log4j is still a compile time dependency for now. http://jakarta.apache.org/commons/logging/tech.html

Warning
log4j.jar MUST be in the same directory as commons-logging.jar. The lowest classloader level they should be put in is common/lib. The recommended is shared/lib, or in a specific webapp's WEB-INF/lib directory.

OpenRC

Tomcat is started and stopped the same as any service on Gentoo:

root #/etc/init.d/tomcat-x.y [ start | stop | restart ]

Tomcat's standard web applications

By default we do not install Tomcat's admin, docs, or examples web application. We do, however, install Tomcat's ROOT and manager applications. However per upstream Tomcat policy, no usernames or passwords are configured by default. /etc/tomcat-x.y/tomcat-users.xml should be modified to add users:

Troubleshooting

If you have problems, please stop and think if the problem is Gentoo related, or Tomcat specific. If you are not sure, please start with the Gentoo Java community and Team, which can be reached via the gentoo-java mailing list, or #gentoo-java (webchat) IRC channel on Freenode. Please file and report Gentoo related bugs, feature enhancement requests, etc. to http://bugs.gentoo.org/

Missing naming-factory-dbcp.jar

Currently the naming-factory-dbcp.jar is not build by default. To build that jar Tomcat robs .java source files from 3 other commons packages, collections, pool, and dbcp. There is no clean solution to compiling this jar at this time. Suggestions, patches, or any assistance on compiling that jar is greatly appreciated.

There are alternatives to this jar. You can use commons-dbcp.jar, or use the factory provided by most all jdbc drivers.

Note
For the time being anyone who needs that jar should fetch it from a binary release of Tomcat 5.0.x or 5.5.x. Just place the jar into common/lib and you will be all set.

Future

Future possibilities for Tomcat on Gentoo

These are some features which are either in consideration, under development, or are only a dream. Ideally to be implemented in the order listed below.

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: William L. Thomson Jr. (author), Joshua Nichols (editor) on February 3, 2007
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.

Retrieved from "https://wiki.gentoo.org/index.php?title=Project:Java/Tomcat_5_Guide&oldid=359026"