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