Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Architecture and Install

The Tomcat Directory Layout

Explore every folder in a Tomcat installation: bin, conf, lib, logs, temp, webapps and work. Learn what each configuration file does and which folders are safe to delete.

An unpacked Tomcat looks like a handful of folders and files, yet each has a precise job. Knowing which ones hold your data, which hold Tomcat's program and which Tomcat regenerates saves you from broken upgrades and surprise data loss. This lesson tours the layout, then builds a copy of it with Java so you can see the structure as a tree.

The folders

TEXT
tomcat/
  bin/        start/stop scripts, bootstrap.jar, tomcat-juli.jar
  conf/       configuration files (you edit these)
  lib/        Tomcat's own JARs, shared by Tomcat and all web apps
  logs/       log files
  temp/       temporary files used by the JVM and Tomcat
  webapps/    web applications (WARs and unpacked folders)
  work/       compiled JSPs and other generated working files
  LICENSE  NOTICE  RELEASE-NOTES  RUNNING.txt

Who owns which folder?

bin, lib Tomcat program: replaced on upgrade
conf Your configuration: keep and back up
webapps Your applications
logs, temp, work Generated: safe to clear when stopped

Upgrade = replace bin and lib, keep the rest.

1 / 2

bin

Contains catalina.sh and catalina.bat (the main launcher), startup, shutdown, configtest, version, setclasspath and digest (to create password hashes). Two JARs live here because they must be on the very first class path: bootstrap.jar (the class that starts Tomcat) and tomcat-juli.jar (the logging implementation). You can add setenv.sh here; it does not exist by default.

conf

File Purpose
server.xml The main file: servers, services, connectors, engines, hosts. See Catalina architecture.
web.xml Defaults applied to every web app (default servlet, JSP servlet, MIME types, session timeout).
context.xml Defaults applied to every context (resources, session persistence).
catalina.properties Class loader paths, package access lists, security package lists.
catalina.policy Security Manager policy (used only when started with -security).
logging.properties Logging configuration for JULI (logging lesson).
tomcat-users.xml Users and roles for the file-based realm, e.g. for the Manager app.
jaspic-providers.xml, *.xsd Message authentication providers and schemas.
Catalina/localhost/ Created at first start: per-application context descriptors (context descriptors).

lib

All JARs here form the common class loader: the Servlet API, JSP and EL implementations, Catalina itself, the JDBC connection pool, and anything you add that all web applications must share, such as a JDBC driver for a container-managed pool. Be careful: whatever you put in lib is visible to every application (class loading).

logs

catalina.out (console output when started with the scripts), catalina.YYYY-MM-DD.log, localhost.YYYY-MM-DD.log, localhost_access_log.YYYY-MM-DD.txt, manager.*.log and host-manager.*.log. They grow forever unless rotated.

temp and work

temp is the JVM's java.io.tmpdir for Tomcat. work holds a folder per host and context (work/Catalina/localhost/shop/) with compiled JSP servlets and session files. Both are safe to empty while Tomcat is stopped, which is a common fix for odd JSP behavior after an upgrade.

webapps

The appBase of the default host. Out of the box it contains ROOT (the welcome page, served at /), docs, examples, manager and host-manager.

Building the tree in Java

This program creates the standard layout in a temporary directory, writes a few placeholder files and prints the tree, marking which folders you maintain. It is a stand-in that shows the structure; no real Tomcat files are involved.

Java Create and print a Tomcat-like tree (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

What survives an upgrade

A safe upgrade procedure follows from the table of ownership:

  1. Stop Tomcat.
  2. Unpack the new version into a new folder.
  3. Copy your changed conf files into it. Do not blindly overwrite the new conf with the old one; compare the files, because defaults change between versions (new connector attributes, removed settings).
  4. Copy your applications and any extra JARs you added to lib.
  5. Clear work and temp, start, and check the logs.

The idea of keeping your files separate from Tomcat's program files is formalized by CATALINA_BASE, the next lesson. With it you never need to copy anything at all.

Spotting configuration drift

Because conf is the only part you edit, a tool that lists the files you changed compared with a pristine copy is useful. This stand-in compares two small "conf" maps by checksum and prints what changed.

Java Which conf files did I change? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Common mistakes

  • Editing files inside webapps/yourapp/ while Tomcat runs and expecting them to survive a redeploy from a new WAR: the unpacked folder is replaced.
  • Putting application JARs in lib "to fix a class not found error" and later suffering version conflicts between apps.
  • Forgetting log rotation, then filling the disk with catalina.out.
  • Deleting conf/Catalina/localhost descriptors without realizing they define contexts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder is safe to empty while Tomcat is stopped, to clear compiled JSPs?

    work holds generated files such as compiled JSP classes. Tomcat recreates them. conf, lib and bin are not regenerated.
  2. 2. Which file defaults apply to every web application you deploy?

    conf/web.xml defines the default servlet, JSP servlet, MIME types and other defaults inherited by all web apps.
  3. 3. What does everything in the lib folder have in common?

    lib JARs are shared by Tomcat and all applications, which is why adding application libraries there is risky.
  4. 4. Which folder contains the unpacked applications and WARs by default?

    webapps is the appBase of the default host.

Summary

  • bin and lib are Tomcat's program; conf and webapps are what you maintain; logs, temp, work are generated.
  • server.xml, web.xml and context.xml in conf carry most configuration; logging.properties and tomcat-users.xml are next.
  • lib is shared by every web app, so keep it lean.
  • Upgrades replace program files and merge, not overwrite, configuration.
  • CATALINA_BASE (next lesson) separates your files from Tomcat's.

Next: Catalina architecture