Apache Tomcat Overview

What is Apache Tomcat — and Why Does it Matter Specifically?

The previous page described the Servlet Container as an abstract contract — a specification any runtime can implement. Apache Tomcat is the concrete, most widely deployed implementation of that contract: an open-source project under the Apache Software Foundation implementing the Jakarta Servlet, Jakarta Server Pages, and Jakarta WebSocket specifications. Writing a compliant @RestController or a raw HttpServlet is only half the picture — something has to actually be the running process that hosts it, and for the large majority of Java web applications today, that something is Tomcat, whether installed standalone or embedded inside a Spring Boot JAR.

// BEFORE — a perfectly correct, compliant Servlet with nothing running it
public class OrderStatusServlet extends HttpServlet { /* ... */ }
// Compiled, packaged into a WAR — and going nowhere until some concrete
// implementation of the Servlet spec agrees to load and run it.

// AFTER — Tomcat is that concrete implementation
$ ./bin/startup.sh
$ cp target/myapp.war /opt/tomcat/webapps/
// Tomcat detects the WAR, extracts it, instantiates every Servlet inside it
// according to the exact lifecycle covered on the previous page, and the
// application is live at http://localhost:8080/myapp

Version, Java baseline, and package namespace

Directory Structure

apache-tomcat-10.1.x/
├── bin/                    ← startup/shutdown scripts
│   ├── startup.sh / .bat  (start)
│   ├── shutdown.sh / .bat (stop)
│   ├── catalina.sh        (main script, more options — "catalina.sh run" for foreground output)
│   └── setenv.sh          (YOUR custom JVM options go here — never edit catalina.sh itself)
│
├── conf/                   ← configuration files
│   ├── server.xml         (main server configuration)
│   ├── context.xml        (default context/resource settings, shared by every app)
│   ├── tomcat-users.xml   (Manager app credentials)
│   └── logging.properties
│
├── lib/                   ← Tomcat's own JARs (servlet-api, jsp-api, etc.)
├── logs/                  ← catalina.out is the first place to look for any error
├── webapps/               ← YOUR APPLICATIONS GO HERE — drop a WAR, it auto-deploys
└── work/                  ← compiled JSPs, session data — safe to clear

• webapps/: drop a WAR here for automatic deployment
• conf/: everything configurable; server.xml is the file you'll edit most
• logs/: the first place to check when anything goes wrong — catalina.out captures all console output

Installing and Running Tomcat

Download and extract

# From https://tomcat.apache.org/
tar -xzf apache-tomcat-10.1.x.tar.gz
cd apache-tomcat-10.1.x
chmod +x bin/*.sh
./bin/startup.sh          # or: ./bin/catalina.sh run  (foreground, output in terminal)
# http://localhost:8080 should now show the Tomcat welcome page
./bin/shutdown.sh

Package manager

# Ubuntu/Debian
sudo apt install tomcat10

# macOS (Homebrew)
brew install tomcat

Setting JVM options the right way

# bin/setenv.sh — create this file yourself; never edit catalina.sh directly,
# since that file is replaced on every Tomcat version upgrade
CATALINA_OPTS="$CATALINA_OPTS -Xms512m"
CATALINA_OPTS="$CATALINA_OPTS -Xmx2048m"
CATALINA_OPTS="$CATALINA_OPTS -XX:+UseG1GC"
CATALINA_OPTS="$CATALINA_OPTS -Dspring.profiles.active=production"
export CATALINA_OPTS

Key Configuration Files

server.xml — the main configuration

<!-- conf/server.xml -->
<Server port="8005" shutdown="SHUTDOWN">
    <Service name="Catalina">
        <Connector
            port="8080" protocol="HTTP/1.1"
            connectionTimeout="20000"
            maxThreads="200"
            redirectPort="8443" />

        <Engine name="Catalina" defaultHost="localhost">
            <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
                <Valve className="org.apache.catalina.valves.AccessLogValve"
                       directory="logs" pattern="%h %l %u %t "%r" %s %b" />
            </Host>
        </Engine>
    </Service>
</Server>

tomcat-users.xml — Manager authentication

<!-- conf/tomcat-users.xml -->
<tomcat-users>
    <role rolename="manager-gui"/>
    <role rolename="manager-script"/>
    <user username="deploy-bot"
          password="${MANAGER_PASSWORD}"
          roles="manager-script"/>
</tomcat-users>

context.xml — shared resources (this is where JNDI actually lives)

<!-- conf/context.xml — this is the concrete, Tomcat-specific home for the
     JNDI resource-binding pattern referenced on the "What is an Application
     Server?" page: the server configures the actual connection, application
     code only ever looks it up by name. -->
<Context>
    <Resource
        name="jdbc/shopDB"
        auth="Container"
        type="javax.sql.DataSource"
        driverClassName="org.postgresql.Driver"
        url="jdbc:postgresql://db.internal:5432/shop"
        username="${DB_USER}"
        password="${DB_PASSWORD}"
        maxTotal="100" maxIdle="30" maxWaitMillis="10000"/>
</Context>

Deploying Applications

Drop the WAR (simplest, fine for a single standalone instance)

cp myapp.war /opt/tomcat/webapps/
# Tomcat detects it, extracts to webapps/myapp/, deploys, live at /myapp
# Undeploy: remove BOTH the WAR and the extracted directory
rm /opt/tomcat/webapps/myapp.war
rm -rf /opt/tomcat/webapps/myapp

Manager web interface

# http://localhost:8080/manager/html — login with tomcat-users.xml credentials
# Upload a WAR, or start/stop/reload/undeploy an existing application

Context paths — the WAR filename determines the URL

webapps/ROOT.war       → http://localhost:8080/
webapps/api.war        → http://localhost:8080/api
webapps/v2#api.war     → http://localhost:8080/v2/api   // "#" encodes a nested path segment

Tomcat's Internal Architecture

This hierarchy maps directly onto the request lifecycle stages covered on the "What is an Application Server?" page — here's exactly where each stage lives inside Tomcat's own component model and configuration files.

Virtual Threads in a Standalone Tomcat Install

The Virtual Threads capacity-planning shift covered on the "What is an Application Server?" page applies to Tomcat itself, not only to Spring Boot's embedded usage of it. On Java 21+, Tomcat 10.1+ can back its request-handling Executor with virtual threads instead of a bounded platform-thread pool.

// If Tomcat is embedded via Spring Boot 3.2+, this is the supported,
// well-documented path — covered in full on the previous pages:
spring.threads.virtual.enabled=true

// For a STANDALONE Tomcat instance (not Spring Boot embedded), the same
// capability is exposed through server.xml's Executor configuration on
// Tomcat 10.1.x+ running on Java 21+. The exact element and attribute names
// have evolved across recent point releases faster than most Tomcat
// configuration — check the release notes for the specific 10.1.x/11.x
// version you're running rather than copying a syntax from an older guide.

Troubleshooting Common Issues

Tomcat won't start

lsof -i :8080                       # Linux/Mac — is the port already taken?
netstat -ano | findstr 8080         # Windows equivalent
tail -f logs/catalina.out           # the error is almost always right here
# Common causes: port conflict, JAVA_HOME unset, insufficient file permissions,
# a corrupted WAR that fails to extract

Application won't load

tail -f logs/localhost.YYYY-MM-DD.log
# Common causes: missing dependency in WEB-INF/lib, a malformed web.xml,
# a javax/jakarta package mismatch against this Tomcat version, or the
# application's own database connection failing on startup

Out of memory

# bin/setenv.sh
CATALINA_OPTS="-Xms1024m -Xmx4096m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/tomcat/logs/"
# The Manager app's "Find leaks" tool can help identify a leaking classloader
# after repeated hot redeploys — a common source in development environments

Slow under load with healthy CPU

# This is the classic thread-pool-exhaustion-while-idle signature covered
# in the Virtual Threads section above — check thread pool saturation first
<Connector port="8080" maxThreads="500" />   // a band-aid; diagnose the real bottleneck first

Production Best Practices

Interview Questions