Mailing-List: contact tomcat-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: tomcat-dev@jakarta.apache.org
Message-ID: <3B45EF3A.7000100@stinky.com>
Date: Fri, 06 Jul 2001 10:02:50 -0700
From: Alex Chaffee <guru@stinky.com>
Reply-To: alex@jguru.com
Organization: jGuru / Purple Technology
User-Agent: Mozilla/5.0 (X11; U; Linux 2.4.5 i686; en-US;
 rv:0.9.1) Gecko/20010608
MIME-Version: 1.0
To: tomcat-dev@jakarta.apache.org
CC: alex@jguru.com, imf@neo.com, mslinn@mslinn.com
Subject: DOC: Table of Contents
Content-Type: multipart/mixed;
 boundary="------------010807060906060304040000"

This is a multi-part message in MIME format.
--------------010807060906060304040000
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Here's my current Table of Contents. As I said in an earlier message,

 > I'd like to organize this TOC as a little more abstract than a simple 
table of contents. Each section should be organized to contain not just 
our original documents, but also a list of other resources on that 
topic. This will be a good way to get a useful set of docs up and 
running quickly. In fact, I imagine that many of the chapters will 
remain unwritten for a while, since there may be existing documents, or 
articles, or FAQ entries that cover the topic (even if not exclusively).

 > In short, I propose that writing a TOC is a very important first 
step, and that this TOC should live a life of its own as a standalone 
document, containing links to other docs, and meta-information like 
links to other docs as well.

I used emacs outline mode, which uses * to represent header level, so we 
don't have to renumber all the chapters all the time.
  * = part
  ** = chapter
  *** = section

For the Security chapter, I took the outline Antony wrote. I trust the 
current discussion thread will improve upon it.

Since there's a lot of detail in here, here's the outline to one level 
of headers only:

* Part I: Installation Guide
** Overview
** Pre-Installation
** Installation Standalone
** Server lifecycle management
** Secure Server (SSL)
** Virtual Hosts
** Installing Jasper (JSP)
** Logging
** Load Balancing
* Part II: Installation Behind A Web Server
** Installation Behind a Web Server Overview
** Behind Apache
** Behind IIS
** Behind iPlanet
* Part III: Deploying Web Applications in Tomcat
** Web Application Primer
** The Web application directory structure
** Deploying your Web applications
** Reloading
** Aliasing and redirecting
** Security
** Developing with Jasper (JSP)
* Part IV: Performance
** Performance Tuning Web Applications
** Tuning the server
** Load Balancing
* Part V: Tomcat Development
** Tomcat 3.x vs 4.x
** Overview of Tomcat code base
** Downloading the source code
** Building the source code
** Bugs
** Developing Interceptors (Tomcat 3.x)
** Developing Valves (Tomcat 4.x)
** Developing Connectors
** Using Tomcat Utility Classes
* Appendices
** server.xml documentation
** web.xml documentation
** Glossary
** Resources

A note on copyright: I'm claiming copyright for this document, since I 
may use parts of it to write articles or books, and I haven't done the 
research on what it means to post text (as opposed to code) into an 
Apache project. I'd contribute it explicitly as open source if I were 
sure I'd keep my rights to use it too. If anyone can enlighten me on 
this topic, please respond with a separate subject line (like 
"Copyrights") so we can keep discussions of copyright separate from 
discussions of the table of contents itself. The copyright will not 
prevent other Apache contributors from using or editing it or adding it 
to the code base -- that is, I want to preserve *my* right to use it in 
a non-Apache context, but also to grant Apache the right to use it too. 
If that's even possible. I'm confused.

Anyway, here it is :-)

Next steps:
comments & revisions ad infinitum
flag each section as applicable to 3.x, 4.x, or both
add links to existing documents
volunteer authors to write chapters/sections

-- 
Alex Chaffee                       mailto:alex@jguru.com
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/

--------------010807060906060304040000
Content-Type: text/plain;
 name="tomcat-book-outline.txt"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="tomcat-book-outline.txt"

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.


* 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"


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


** Overview

Big picture, 30,000 foot view.

*** Diagram of all the parts of Tomcat 
**** Servlet Container
***** Directories
***** Config files
***** Web apps
***** Connectors

*** Basic terms
**** servlet
**** web app
**** see glossary [in fact, maybe this whole section should be removed
in favor of the appendix]


** Pre-Installation

Covers what to do before you "actually" install Tomcat. 

*** DIAGRAM: Flowchart of installation steps 
**** Choose OS
**** Install Java
**** Download Tomcat
**** etc.

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

*** Choosing an OS

Religious rants here :-)

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

**** Downloading JDK
**** Setting environment variables
**** Setting class path (see Tomcat Classpath section)
**** OS Issues

*** Choosing a Tomcat Version
**** 3.x vs. 4.x
    - see also "Development:3.x vs 4.x" chapter
**** 3.1 vs 3.2 vs 3.3
**** 4.0 status

*** Downloading Tomcat
**** Binary distribution
**** Source distribution
**** CVS (see "developing" section)


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

*** HIGHLY recommended to install standalone first

*** Basic procedure

*** Windows Issues
**** Where to place TOMCAT_HOME?
**** Port 80
**** Admin user
**** Running as a service

*** Unix Issues
**** Where to place TOMCAT_HOME?
**** Port 80
**** Redirector
**** root user
**** Running as a daemon

*** Testing your basic standalone installation
**** The Example Context (Webapp)
**** telnet from same machine
**** web browser


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

*** Starting Tomcat
*** Stopping Tomcat
*** Checking if Tomcat is running
*** Automatically restarting [=reloading?]    
*** [Log rotation? See "logging" chapter]

*** The Admin Context (Costin?)
*** The Tomcat Manager Application (Craig?)


** 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)

*** Overview of SSL - what it is and isn't
*** Acquiring a key
*** Where to install your key
*** Pointers to other chapters


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

*** Context-based

*** Multiple roots

*** Reference to Virtual Hosts in "Behind" chapters
**** Apache
**** IIS
**** iPlanet


** Installing Jasper (JSP)

*** JSP Primer
*** Enabling the Jasper servlet
*** Disabling the Jasper servlet
*** Precompiling JSPs
*** Where are JSP files stored 
**** source
**** compiled .java
**** compiled .class
*** Choosing a compiler
*** Debugging a JSP


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

*** Log management
*** System.out and System.err
*** Server/JSP log output
*** Log file rotation
*** Custom logging


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

** Installation Behind a Web Server Overview

*** Behind mode overview
*** Connector protocols
**** AJP12
**** AJP13
**** AJP14

** Behind Apache

*** basic installation
*** Choosing a mod
**** mod_jserv
**** mod_jk
**** mod_webapp
*** httpd.conf-auto
**** different versions' idiosyncracies
*** Enabling SSL
*** Virtual Hosts
*** JSP integration
*** Logging
*** Authentication

** Behind IIS

*** Installation steps
*** Enabling SSL
*** Virtual Hosts
*** JSP integration
*** Logging
*** Authentication

** Behind iPlanet


* Part III: Deploying 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.

** Web Application Primer

*** See Web Application Developer's Guide
*** What's a servlet
*** What's a JSP
*** What's a webapp

** The Web application directory structure

*** Context root
*** The WEB-INF directory
*** WEB-INF configuration files
*** WEB-INF/servlets
*** WEB-INF/classes
*** WEB-INF/lib
*** WAR Files
**** Using the jar tool to make a WAR file
**** Where to place the WAR file

** Deploying your Web applications
*** Telling Tomcat where your web applications are
**** webapps directory
    - redeploying gotcha
**** WAR files
**** unpacked webapps

** Reloading

*** Reloading webapps
*** Reloading servlets
*** Reloading classes
*** Restarting the server

** Aliasing and redirecting

*** Inside Tomcat
**** Webapp contexts
**** Using web.xml
*** Inside Web Server
**** Apache
**** IIS
**** Others
*** Examples
**** (several examples)
*** See also Virtual Hosts chapter

** Security

*** Concepts - Explanation of J2EE and Java 2 security models

*** Transport-Level Security
**** SSL

*** Authentication
**** Authentication with Realms
***** Simple realm
***** JDBC Realm
***** Custom realms

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

*** Java 2 security policy

** Developing with Jasper (JSP)

*** JSP Overview
*** Some JSP Gotchas
*** Using JSP Explorer
*** JSP Error Tracking


* Part IV: Performance

** Performance Tuning Web Applications

** Tuning the server
*** Thread pool size

** Load Balancing


* Part V: Tomcat Development

Covers actually writing code for the Tomcat code base.  

** Tomcat 3.x vs 4.x

** Overview of Tomcat code base

** Downloading the source code

*** Using CVS
*** Downloading

** Building the source code
*** Using Ant
*** Contents of "build" directory
*** Using Ant to build your own Web apps 
	[misplaced? should go in Developing Web Apps guide?]

** Bugs
*** Submitting Bugs
*** The Bug Database(s)
*** Fixing Bugs

** Developing Interceptors (Tomcat 3.x)

** Developing Valves (Tomcat 4.x)

** Developing Connectors

***  mod_jserv
***  mod_jk
***  mod_webapp

** Using Tomcat Utility Classes
*** What the Apache license means to you


* Appendices

** server.xml documentation

** web.xml documentation

** Glossary

** Resources
*** Mailing Lists
*** FAQs and online documentation
*** Other Web Sites


----


----

--------------010807060906060304040000--