You may want to set the environmental variables CATALINA_PID or CATALINA_OPTS in addition to CATALINA_HOME and JAVA_OPTS. The first specifies a location of where to store the pid file, and this is a must when running multiple instances on UNIX or Cygwin. (The UNIX init script included in the Starting a Tomcat Instance chapter sets this automatically). I don't know the implications of setting a PID file on Windows without Cygwin.

CATALINA_OPTS is immensely useful for setting debug parameters, Java memory settings, etc. One very common use is to set the system property java.awt.headless to true. Most graphical applications (like Jasper, JFreechart, LiquidOffice, StyleReport, etc.) will halt Tomcat when they render if something isn't done to disable display rendering, and this is by far the easiest method. (This problem occurs with most J2EE servers, not just Tomcat). Here's how to make this setting in UNIX.

    export CATALINA_OPTS: CATALINA_OPTS=-Djava.awt.headless=true

Start up Tomcat with the command %CATALINA_HOME%\catalina.bat start on Windows, or $CATALINA_HOME/catalina.sh start on UNIX. You must have the environmental variables CATALINA_HOME and CATALINA_BASE set, or the startup won't work right.

Connect up to the home page and drill down to the Manager web app. Unless you specifically want to use Webdav or Tomcat clustering, undeploy the applications webdav, balancer, host-manager,

Drill down to the Administration web app from the hom page to add more accounts, global J2EE datasources or mail servers, access logs, and IP address restrictions. Make sure to Commit changes that you make (although Committing is not necessary for user/role modifications), but don't expect your changes to become active until Tomcat is restarted. See the Tomcat Quirks chapter about Admin app quirks.

See the Tomcat-Bundled Web Apps chapter about the Tomcat administrative web apps, and the Securing Tomcat's Administrative Web Apps chapter about how to secure them.

CATALINA_BASE/logs will contain the Tomcat logs for this instance.

Shut down Tomcat with the command %CATALINA_HOME%\catalina.bat stop on Windows, or $CATALINA_HOME/catalina.sh stop on UNIX.

If you are not using J2EE/JNDI to obtain your resources, then ignore this section because your resources are handled entirely by your application. This would be the case if your web app is coded like a standalone app (w.r.t. obtaining resources), or if you use Spring (without JNDI lookups). The remainder of this chapter assumes that you want to use J2EE or JNDI resources.

With Tomcat, one can define all resources at the application level. I explain the more common J2EE idiom where objects are defined at the global level and these global resources are allocated to the applications.

The basic strategy to use global resources in Tomcat is to define the global resources in CATALINA_BASE/config/server.xml, perhaps using the Tomcat Administration web app, then create application-specific JNDI links to these resources in your applications' <Context> elements of server.xml, or (usually better), in the application's context.xml file. The context.xml file is a Tomcat-specific descriptor which you bundle into your web app's META_INF directory. Tomcat will effectively add the contents of this file to your application's virtual server.xml <Context> element. When you deploy, Tomcat will copy your context.xml file to CATLINA_BASE/conf/Catalina/localhost/<APPNAME>.xml. It functions as a link between vendor-portable J2EE descriptors and Tomcat, in the same way that weblog.xml is the Weblogic-specific links vendor-portable J2EE descriptors to Weblogic.

I'll explain how to use the single Tomcat Memory Based Realm. This is great for development use, because you can use the single text user/role list for as many applications as you wish, and you can maintain the list with the Tomcat Administration web app or a text editor. You should obviously use https and protect the password file if your application is accessible to external users. Once you have the Memory Based Realm set up and working, it will much easier for you to understand and follow the instructions in the Tomcat docs for production quality realm implementations.

The "User Definition" section of the nav panel of the Tomcat Administration panel can be used to graphically edit the file CATALINA_BASE/conf/tomcat-users.xml. Sometimes changes become active right away, but usually you will have to restart Tomcat.

The Admin web app works well to define global J2EE data sources. Tomcat will wrap your data sources with dbcp connection pooling unless you override with custom configuration.

Applications should be able to access data sources with global JNDI names, but I've never been able to get that to work with Tomcat. Using app-specific resource-refs to the global data sources works fine, however.

Tomcat logs to files in CATALINA_BASE/logs.

stdout and stderr from your running applications will find their way into the file catalina.out. Servet.log() entries make it to the localhost log file.

For application logs, you can use ${catalina.base} in your log4j config files, since tomcat sets this system property for out. This avoids multiple Tomcat instances from clobbering the same appender output files.