• Launchpad Entry: tomcat6

  • Created: Aug 1st, 2008

  • Contributors: ThierryCarrez

  • Packages affected: tomcat6


Tomcat 6 is used by lots of Java developers and integrators to test and deploy Java web applications. Currently the tomcat6 source package only builds the Servlets and JSP API jars, it needs to be extended to support a complete Tomcat 6 stack. It should provide features making it easy to use for Java developers in private instances.

Release Note

Ubuntu features a Servlet 2.5 / JSP 2.1 compliant, lightweight webapp container through the introduction of a full Apache Tomcat 6 server stack, together with features making it easy to use by developers in private instances.


Most Java web applications developers use the Tomcat lightweight reference implementation to test and deploy their Servlet/JSP webapps. Only Tomcat 5.5 (Servlet 2.4 / JSP 2.0 compliant) is available in Ubuntu today. Tomcat 6.0 has been released in late 2006 and is now at version 6.0.18 a perfectly mature product. In order to be considered as a potential Java webapp development / deployment target, Ubuntu needs to include a useable Tomcat 6 server stack.

Use Cases

Josh is a Java developer and wants to deploy his latest web applications on a test server to show his boss how well he did. He quickly sets up an Ubuntu machine and installs the provided Tomcat 6 web application server.

Julia looks for the ideal deployment environment for her small company web applications in production. Their application do not use any of the Java EE complex features, she just needs Servlet / JSP support. After careful testing, she picks up Ubuntu Server with the lightweight Tomcat 6 server as the best tool for the job.

Jeremy is a Java web application developer with a user account on a server running Ubuntu. He uses the tools in the official Tomcat 6 packages to set up a private Tomcat instance that he can run with user privileges.


Tomcat6 already exists as a source package in universe (synced from Debian), currently providing libservlet2.5-java. It would be extended to address the full range of features. It would be nice if our packaging was accepted into Debian rather than them pushing out their own version of tomcat6 in the future.

We should therefore collaborate with the debian-java team early in the implementation phase so that they can comment on what we should change in our packaging to increase our odds to get the package synced back to Debian.


Main differences with tomcat5.5

The new packaging for tomcat6 is loosely based on the work done in Tomcat 5.5, with the following notable differences:

  • Support for creating multiple user private instances of Tomcat 6 (based on the CATALINA_BASE features described in Tomcat 6.0 RUNNING.txt file), without having to install a system-wide instance.
  • Split the "-webapps" package into "-docs" and "-examples"
  • A default customized minimal ROOT webapp is installed with the "tomcat6" package to check everything is OK and point to the next packages to install

Strict CATALINA_BASE implementation

Tomcat 6 usually runs from a single directory containing predefined subdirectories (bin/ conf/ webapps/ logs/ ...) called CATALINA_HOME. To support multiple instances of Tomcat running at the same time, Tomcat proposes to specify a CATALINA_BASE directory that would include a subset of those directories with specific items (essentially conf/ and webapps/). This is described in the RUNNING.txt file.

The idea is to strictly implement this by providing a package that installs a regular CATALINA_HOME, then packages that provide proper CATALINA_BASE directories, in order to support multiple instances (in particular system-wide and user-private ones) to run in parallel in "the Tomcat6 recommended way". The goal is to make developers use the packaged tomcat6 rather than unzipping their own.

Webapps location

There is work in progress to support a webapp deployment framework in Ubuntu. Even if this framework doesn't exist yet, we must try to install things in a way that would be compatible with what we expect it to be.

The framework might feature a two-step install process for web applications in general. One is installing the files on the system (dpkg -i), and the other is deploying a given web application in a given virtual host / domain / instance of a web application server (webapp-deploy). Web applications should therefore be separated from the server package that happens to deploy them.

To follow FHS and Debian webapp policy, each web application should be deployed as a single subdirectory of /usr/share/PACKAGE-NAME.

Proposed package set

  • libservlet2.5-java, libtomcat6-java: pure Java library packages installed in /usr/share/java following Debian Java library policy.

  • tomcat6-common: package implementing CATALINA_HOME in /usr/share/tomcat6
  • tomcat6: package installing the system-wide instance, with a CATALINA_BASE in /var/lib/tomcat6 and links to conform to FHS. This package depends on tomcat6-common. It installs a minimal ROOT webapp.
  • tomcat6-user: package providing a skeleton directory and a tomcat6-instance-create tool to create your own private instance of tomcat6 (a CATALINA_BASE directory in your home). This package depends on tomcat6-common, so it does not require the system instance to be installed. No webapp is pre-installed, as this is geared towards Java developers.
  • tomcat6-admin, tomcat6-docs, tomcat6-examples: packages containing the Tomcat6 webapps, for the moment autodeployed in the tomcat6 system-wide instance (to be changed when the webapp framework will be available).

Other fixes to include

  • Full support of the default Java options in Intrepid (OpenJDK-6...) using the new Java virtual packages
  • The catalina.policy file will be autogenerated in /var/cache/tomcat6 rather than /etc/tomcat6.


The current tomcat6 source package will be extended to provide the new packages as discussed. There won't be any conflict with tomcat5.5 packages as they are using separate namespaces. There won't be any upgrade problems as those are new packages.

Test/Demo Plan

$ sudo apt-get install tomcat6

Access the default start page (by default at http://theserver:8080/) that points to the webapps you can install.

$ sudo apt-get install tomcat6-admin tomcat6-docs

Access the admin webapp and the docs.

$ sudo apt-get purge tomcat6
$ sudo apt-get install tomcat6-user
$ tomcat6-instance-create mytomcat6
$ ls mytomcat6
$ mytomcat6/bin/

Access the user instance at http://theserver:8080/

Outstanding Issues

The Tomcat 6 native APR has been left out of the scope of this spec. It can be added as an extra binary package at a later stage, in order to improve performance and have potential integration with an Apache server.

The package should be upgraded to 6.0.18 as well.

BoF agenda and discussion

Please add your comments here.

webapps location

MathiasGug: IMO, webapps should be put in /usr/share/PACKAGE-NAME/ to comply with the FHS. See 3.1 Web applications and the FHS for an explanation. The deployment phase would be probably be handled with a sort of registry, where each webapps would drop a descriptor file outlining which kind of environment it requires to be deployed (J2EE, apache+php, RoR).

Future improvements

ThierryCarrez: Support for changing ports for user instance directly in tomcat6-instance-create


Tomcat6StackSpec (last edited 2008-08-06 17:00:55 by localhost)