OK, at Craig's request, here's the current Table of Contents for Tomcat docs. (I wrote a program to convert *** to 1.2.3. format so it's easier to read.) It just occured to me that maybe the TOC will be applicable to both versions (3 vs 4), even though the content of each chapter will be completely different. I think there's actually value in synchronizing the TOCs of two different books, though maybe I'm just being weird :-) -- Alex Chaffee mailto:[EMAIL PROTECTED] jGuru - Java News and FAQs http://www.jguru.com/alex/ Creator of Gamelan http://www.gamelan.com/ Founder of Purple Technology http://www.purpletech.com/ Curator of Stinky Art Collective http://www.stinky.com/
This document Copyright (C) 2001 by Alex Chaffee. All rights reserved. Permission is granted for the Apache project to incorporate it in whole or in part into their documentation. Part 0: Editorial Notes The "installation" unit is the most crucial. I think there should be a chapter or series of chapters on installing Tomcat standalone, that covers *everything* or almost everything start-to-finish. Then we also need separate chapters for installing behind each Web server. Then come chapters on administration and advanced configuration issues. We should make it clear that it is *HIGHLY* recommended to install standalone first. This will help the users debug their setups. It will also help us organize the docs. Each "behind" chapter will assume you've read the "standalone" chapter(s). http://jakarta.apache.org/tomcat/tomcat-3.3-doc/appdev/deployment.html is very well organized and would be great as a "Web Application Developer's Guide" Should we actually organize Part I and Part II as parts of a larger Installation Guide, as in Part I: Installation Guide Covers installing Tomcat. Separate instructions (sidebars?) for Windows 9x, Windows NT, Linux, Solaris, Other Unixes, Mac OS. Separate instructions for standalone vs. plug-in. Separate instructions for Tomcat 3.x vs 4.x. 1. Overview Big picture, 30,000 foot view. 1.1. Diagram of all the parts of Tomcat 1.1.1. Servlet Container 1.1.1.1. Directories 1.1.1.2. Config files 1.1.1.3. Web apps 1.1.1.4. Connectors 1.2. Basic terms 1.2.1. servlet 1.2.2. web app 1.2.3. see glossary [in fact, maybe this whole section should be removed in favor of the appendix] 2. Pre-Installation Covers what to do before you "actually" install Tomcat. 2.1. DIAGRAM: Flowchart of installation steps 2.1.1. Choose OS 2.1.2. Install Java 2.1.3. Download Tomcat 2.1.4. etc. 2.2. HIGHLY recommended to install standalone first We should make it clear that it is *HIGHLY* recommended to install standalone first. This will help the users debug their setups. It will also help us organize the docs. Each "behind" chapter will assume you've read the "standalone" chapter(s). 2.3. Choosing an OS Religious rants here :-) 2.4. Installing Java How to install a JDK or JRE on your target platform. It might make sense to break this out into separate chapters per platform, if it turns out a lot of the information is different. 2.4.1. Downloading JDK 2.4.2. Setting environment variables 2.4.3. Setting class path (see Tomcat Classpath section) 2.4.4. OS Issues 2.5. Choosing a Tomcat Version 2.5.1. 3.x vs. 4.x [ see also "Development:3.x vs 4.x" chapter ] 2.5.2. 3.1 vs 3.2 vs 3.3 2.5.3. 4.0 status 2.6. Downloading Tomcat 2.6.1. Binary distribution 2.6.2. Source distribution 2.6.3. CVS (see "developing" section) 3. Installation Standalone This section covers the basic steps of installing Tomcat as a standalone application. It is the core of the Installation Guide. Everyone who reads the later chapters is expected to have read these, and to have a working standalone install before going and installing behind the Web server. 3.1. HIGHLY recommended to install standalone first 3.2. Basic procedure 3.3. Windows Issues 3.3.1. Where to place TOMCAT_HOME? 3.3.2. Port 80 3.3.3. Admin user 3.3.4. Running as a service 3.4. Unix Issues 3.4.1. Where to place TOMCAT_HOME? 3.4.2. Port 80 3.4.3. Redirector 3.4.4. root user 3.4.5. Running as a daemon 3.5. Testing your basic standalone installation 3.5.1. The Example Context (Webapp) 3.5.2. telnet from same machine 3.5.3. web browser 4. Server lifecycle management Maybe this should go in a later Admin guide, but it's important to get the users comfortable with the use of the scripts and stuff early on. Maybe here we just cover starting and stopping, and have a more thorough chapter later on. 4.1. Starting Tomcat 4.2. Stopping Tomcat 4.3. Checking if Tomcat is running 4.4. Automatically restarting [=reloading?] 4.5. [Log rotation? See "logging" chapter] 4.6. The Admin Context (Costin?) 4.7. The Tomcat Manager Application (Craig?) 5. Secure Server (SSL) Covers how to get Tomcat up and running with SSL. Since this is in an Installation guide, it does not cover other aspects of security (but refers to the relevant chapter in the Admin Guide) 5.1. Overview of SSL - what it is and isn't 5.2. Acquiring a key 5.3. Where to install your key 5.4. Pointers to other chapters 6. Virtual Hosts So far, the installation examples have covered the simple case where you are using a single Tomcat server to handle requests for a single domain. In this chapter, we cover using Tomcat to handle requests for multiple domains. Note that we're still talking about standalone Tomcat; getting VHosts to work behind other servers is a topic for later on. 6.1. Context-based 6.2. Multiple roots 6.3. Reference to Virtual Hosts in "Behind" chapters 6.3.1. Apache 6.3.2. IIS 6.3.3. iPlanet 7. Installing Jasper (JSP) 7.1. JSP Primer 7.2. Enabling the Jasper servlet 7.3. Disabling the Jasper servlet 7.4. Precompiling JSPs 7.5. Where are JSP files stored 7.5.1. source 7.5.2. compiled .java 7.5.3. compiled .class 7.6. Choosing a compiler 7.7. Debugging a JSP 8. Logging Maybe this should go in a later Admin Guide, but it's important to at least mention where the logs are during the installation phase. 8.1. Log management 8.2. System.out and System.err 8.3. Server/JSP log output 8.4. Log file rotation 8.5. Custom logging 9. Load Balancing Covers briefly what Load Balancing is. Mentions that as presently written, Tomcat does not support load balancing in standalone mode. Refers to individual web server chapters and to Performance chapter. Basically this is a placeholder for references to other parts (until TC standalone supports load balancing). Part II: Installation Behind A Web Server This unit builds on the standalone unit. Readers are assumed to have read the relevant chapters in the standalone unit, and to have a -working- standalone installation. The structure of these chapters should follow the structure of the standalone unit -- that is, just like the standalone unit had a chapter on basic installation, SSL, virtual hosts, JSP, each Web server-based chapter will have a section on basic installation, SSL, virtual hosts, JSP, in that order. This will allow people to "flip back and forth" or at least to get less confused about what information is Tomcat-general and which is Apache-specific. 1. Installation Behind a Web Server Overview 1.1. Behind mode overview 1.2. Connector protocols 1.2.1. AJP12 1.2.2. AJP13 1.2.3. AJP14 2. Behind Apache 2.1. basic installation 2.2. Choosing a mod 2.2.1. mod_jserv 2.2.2. mod_jk 2.2.3. mod_webapp 2.3. httpd.conf-auto 2.3.1. different versions' idiosyncracies 2.4. Enabling SSL 2.5. Virtual Hosts 2.6. JSP integration 2.7. Logging 2.8. Authentication 2.9. In-Process 3. Behind IIS 3.1. Installation steps 3.2. Enabling SSL 3.3. Virtual Hosts 3.4. JSP integration 3.5. Logging 3.6. Authentication 3.7. In-Process 4. Behind iPlanet 5. Behind Lotus Domino 6. Behind Netware Part III: Administrator's Guide: Deploying and Configuring Web Applications in Tomcat Covers developing and deploying Web Applications inside Tomcat. This follows a fairly clean break between "installing tomcat" and "deploying applications" -- even though there's a lot of configuration in both steps, you can separate problems by "my server isn't running at all" vs. "my server is running but my app doesn't work." It may be better to name this the "Administrator's Guide" which would better suit discussions of things like security and lifecycle which aren't really about *deploying* per se. But if so, the word "deploying" should appear in appropriate chapter titles. 1. Web Application Primer 1.1. See Web Application Developer's Guide 1.2. What's a servlet 1.3. What's a JSP 1.4. What's a webapp 2. The Web application directory structure 2.1. Context root 2.2. The WEB-INF directory 2.3. WEB-INF configuration files 2.4. WEB-INF/servlets 2.5. WEB-INF/classes 2.6. WEB-INF/lib 2.7. WAR Files 2.7.1. Using the jar tool to make a WAR file 2.7.2. Where to place the WAR file 3. Deploying your Web applications 3.1. Telling Tomcat where your web applications are 3.1.1. webapps directory - redeploying gotcha 3.1.2. WAR files 3.1.3. unpacked webapps 4. Reloading 4.1. Reloading webapps 4.2. Reloading servlets 4.3. Reloading classes 4.4. Restarting the server 5. Aliasing and redirecting 5.1. Inside Tomcat 5.1.1. Webapp contexts 5.1.2. Using web.xml 5.2. Inside Web Server 5.2.1. Apache 5.2.2. IIS 5.2.3. Others 5.3. Examples 5.3.1. (several examples) 5.4. See also Virtual Hosts chapter 6. Security 6.1. Concepts - Explanation of J2EE and Java 2 security models 6.2. Transport-Level Security 6.2.1. SSL 6.3. Authentication 6.3.1. Authentication with Realms 6.3.1.1. Simple realm 6.3.1.2. JDBC Realm 6.3.1.3. Custom realms 6.3.2. Authentication with LDAP See ch. 15 of Professional JSP 6.3.3. Authentication with JNDI 6.4. Authorization 6.4.1. J2EE role based In particular, it should try to explain in simpler terms than the API spec how J2EE roles are designed to work, covering the mapping from developer roles to deployment roles. 6.5. Java 2 security policy 7. Developing with Jasper (JSP) 7.1. JSP Overview 7.2. Using jspc to pre-compile your JSPs 7.3. Some JSP Gotchas 7.4. Using JSP Explorer 7.5. JSP Error Tracking 8. Performance 8.1. Performance Tuning Web Applications 8.2. Tuning the server 8.2.1. Thread pool size 8.3. Load Balancing Part IV: Tomcat Development Covers actually writing code for the Tomcat code base. 1. Tomcat 3.x vs 4.x 2. Overview of Tomcat code base 3. Downloading the source code 3.1. Using CVS 3.2. Downloading 4. Building the source code 4.1. Using Ant 4.2. Contents of "build" directory 4.3. Using Ant to build your own Web apps [misplaced? should go in Developing Web Apps guide?] 5. Bugs 5.1. Submitting Bugs 5.2. The Bug Database(s) 5.3. Fixing Bugs 6. Developing Interceptors (Tomcat 3.x) 7. Developing Valves (Tomcat 4.x) 8. Developing Connectors 8.1. mod_jserv 8.2. mod_jk 8.3. mod_webapp 9. Using Tomcat Utility Classes 9.1. What the Apache license means to you Part V: Appendices 1. server.xml documentation 2. web.xml documentation 3. Glossary 4. Resources 4.1. Mailing Lists 4.2. FAQs and online documentation 4.3. Other Web Sites ---- Part VI: To Add To Outline (Somewhere): 1. Using Tomcat inside an IDE ----
