web.xml, context.xml, and Configuration Layers

Introduction

server.xml defines ports and hosts; web.xml and context.xml define how each web application behaves—default servlets, session timeouts, error pages, and optional JNDI resources like a database pool. Tomcat merges settings from global files under conf/, per-application descriptors inside the WAR, and Context fragments on disk. This chapter explains those layers, what to edit where, and how they connect to JDBC DataSource concepts used in Spring Boot.

Prerequisites

• server.xml and Connectors
• Tomcat Directory Layout
• Basic idea of Servlets and HTTP sessions

Three Layers of Configuration

Container (Tomcat)
├── conf/server.xml           ← Connectors, Engine, Host
├── conf/web.xml              ← defaults for EVERY app
├── conf/context.xml          ← default Context for EVERY app
└── conf/tomcat-users.xml     ← Manager / Host Manager users
 
Web application (WAR)
├── META-INF/context.xml      ← optional Context overrides
└── WEB-INF/web.xml           ← servlets, filters, welcome files, errors

Code explanation:

• More specific or later-loaded app config can override inherited defaults
• Spring Boot executable JARs often skip web.xml entirely—standalone Tomcat WARs still use these files frequently

Global web.xml (conf/web.xml)

Tomcat ships a large default conf/web.xml. It registers container-wide components every application inherits, including:

• Default servlet — serves static files (HTML, CSS, JS, images)
• JSP servlet — compiles and runs JSP pages
• Default MIME mappings, welcome-file behavior baseline, session defaults

You rarely edit global web.xml when learning. Instead, override in WEB-INF/web.xml inside your WAR.

Default servlet and static files

The default servlet maps to / and serves files from the WAR root when no other servlet matches:

myapp.war
├── index.html          →  /myapp/index.html  (default servlet)
├── assets/app.js       →  /myapp/assets/app.js
└── WEB-INF/            →  not directly accessible via URL

Code explanation:

• WEB-INF/ is private—browsers must not fetch classes or lib/ JARs over HTTP
• Static frontends (React/Vite dist/ copied into WAR root) rely on the default servlet

Servlet 3+ annotations vs web.xml

Modern apps can declare servlets with @WebServlet instead of XML:

import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
 
@WebServlet("/hello")
public class HelloServlet extends HttpServlet { /* ... */ }

Code explanation:

• metadata-complete="true" in web.xml disables annotation scanning—useful for strict XML-only deploys
• Without it, Tomcat scans WEB-INF/classes for annotations at deploy time

Application web.xml (WEB-INF/web.xml)

Minimal example for a Servlet 4 / Jakarta app:

Register a servlet in XML (classic style)

<servlet>
  <servlet-name>Hello</servlet-name>
  <servlet-class>com.example.HelloServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>Hello</servlet-name>
  <url-pattern>/hello</url-pattern>
</servlet-mapping>

Full URL with context path /myapp:

http://localhost:8080/myapp/hello

Filters follow the same pattern with filter and filter-mapping—order matters for the filter chain.

Global context.xml (conf/context.xml)

Default Tomcat conf/context.xml often enables a WatchedResource and may define shared resources:

<Context>
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
  <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>
</Context>

Code explanation:

• WatchedResource — Tomcat can reload the Context when these files change (behavior depends on reloadable—see below)
• Global context.xml applies to every deployed application unless overridden

Per-Application context.xml

Inside the WAR: META-INF/context.xml

<Context path="/hello" reloadable="true">
  <!-- app-specific resources -->
</Context>

Outside the WAR: Context fragment

conf/Catalina/localhost/hello.xml (for app at context /hello):

<Context docBase="/opt/apps/hello.war"
         reloadable="false"
         unpackWARs="true" />

Code explanation:

• docBase can point to a WAR or exploded directory anywhere on disk
• File name hello.xml → context path /hello (except ROOT.xml → /)
• Preferred for production—upgrade WAR without touching Tomcat home

Details in Deploying WAR and webapps.

reloadable: development vs production

JNDI DataSource in context.xml (Intro)

JNDI (Java Naming and Directory Interface) lets Tomcat expose a javax.sql.DataSource that application code looks up by name—common in traditional Java EE style apps.

1. Put JDBC driver in Tomcat lib/

cp mysql-connector-j-8.x.x.jar $CATALINA_HOME/lib/

Restart Tomcat after adding JARs to lib/.

2. Define Resource in Context

META-INF/context.xml inside your WAR (or localhost fragment):

<Context>
  <Resource name="jdbc/MyDB"
            auth="Container"
            type="javax.sql.DataSource"
            maxTotal="20"
            maxIdle="10"
            maxWaitMillis="10000"
            username="demo"
            password="demo_pass"
            driverClassName="com.mysql.cj.jdbc.Driver"
            url="jdbc:mysql://127.0.0.1:3306/demo?useSSL=false&amp;serverTimezone=UTC"/>
</Context>

Code explanation:

• name="jdbc/MyDB" — JNDI path java:comp/env/jdbc/MyDB
• auth="Container" — Tomcat creates and pools connections (Tomcat DBCP pool)
• & in XML — escaped & in JDBC URL query string

3. Link in web.xml (resource reference)

<resource-ref>
  <description>MySQL DB</description>
  <res-ref-name>jdbc/MyDB</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
</resource-ref>

4. Look up in Servlet code (illustrative)

Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
DataSource ds = (DataSource) envCtx.lookup("jdbc/MyDB");
try (Connection conn = ds.getConnection()) {
    // use connection
}

Code explanation:

• Same DataSource abstraction as connection pooling in JDBC
• Spring Boot usually configures HikariCP in application.yml instead of Tomcat JNDI—both end at a pool, different wiring
• See Spring Boot JDBC DataSource for the Boot-native path

tomcat-users.xml (Manager Access)

conf/tomcat-users.xml defines users for Tomcat’s Manager and Host Manager web apps—not your business application users.

Example (Tomcat 10):

<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml
              http://tomcat.apache.org/xml/tomcat-users.xsd"
              version="1.0">
 
  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <user username="admin" password="change_me_strong"
        roles="manager-gui,manager-script"/>
</tomcat-users>

Generate a hashed password (Tomcat 10+):

cd $CATALINA_HOME
./bin/digest.sh -a SHA-512 your_password

Paste the digest into password="…" with {SHA-512}… prefix per tool output.

Code explanation:

• Restart Tomcat after editing tomcat-users.xml
• Restrict Manager to localhost or VPN in production—see Tomcat Security Basics
• Your Spring Security / session login is configured inside the WAR, not here

How Configuration Merges (Precedence)

Request handling order (conceptual):
  server.xml Host appBase
       → Context (auto, localhost/*.xml, or META-INF/context.xml)
            → WEB-INF/web.xml + annotations
                 → Filters → Servlets

When both global and app web.xml define behavior, the application descriptor adds to or overrides defaults according to Servlet spec merge rules—when unsure, test after deploy and read logs/localhost.*.log.

Spring Boot WAR vs Classic web.xml

Boot apps rarely use Tomcat JNDI DataSources— they use HikariCP from properties. Standalone Tomcat tutorials and older enterprise WARs still use context.xml resources.

Edit and Deploy Workflow

1. Backup: cp conf/context.xml conf/context.xml.bak
2. For app-only changes, rebuild WAR—avoid editing exploded webapps/myapp/ long term
3. For localhost fragments, edit conf/Catalina/localhost/myapp.xml, then reload or restart
4. Check logs:

tail -30 logs/localhost.$(date +%Y-%m-%d).log

5. Hit a test URL:

curl -I http://127.0.0.1:8080/myapp/

Common Mistakes

Post-Chapter Checklist

• Distinguish conf/web.xml vs WEB-INF/web.xml
• Know three Context locations: global, META-INF/, conf/Catalina/localhost/
• Explain welcome-file-list, session-timeout, error-page
• Describe JNDI DataSource at a high level and when Spring Boot makes it unnecessary
• Know tomcat-users.xml is for Manager, not application login

What Comes Next

FAQ

Is WEB-INF/web.xml required?

Not for Servlet 3+ if you use annotations and no required XML-only features—but many teams keep a minimal web.xml for session and error settings.

Can I delete conf/web.xml?

No—Tomcat needs the global defaults. Back it up; do not remove.

context.xml in WAR vs localhost fragment?

WAR-embedded travels with the app; localhost fragment keeps secrets and paths on the server (different docBase per environment).

Same as Spring application.yml?

Conceptually similar environment-specific binding, different mechanism. Boot spring.datasource.url replaces Tomcat JNDI for most new projects.

Why 404 on welcome page?

Missing index.html, wrong welcome-file-list, or wrong context path—not necessarily web.xml on the server.

Does editing global context.xml require restart?

Yes for global conf/context.xml. Per-app redeploy may pick up META-INF/context.xml changes depending on autoDeploy—do not rely on it in production.

Tomcat 9 javax vs Tomcat 10 jakarta web.xml namespace?

Tomcat 10 uses https://jakarta.ee/xml/ns/jakartaee and jakarta.* classes. Tomcat 9 uses Java EE javax.* namespace URLs—match your Tomcat major version.