Apache Tomcat
Apache Tomcat is an open-source implementation of the Jakarta Servlet, Jakarta Server Pages, Jakarta Expression Language, and Jakarta WebSocket technologies, serving as a lightweight web server and servlet container for hosting Java-based web applications.[1] Developed by the Apache Software Foundation, it enables the execution of dynamic web content through servlets and JavaServer Pages (JSP), supporting mission-critical applications across various industries.[2]
The origins of Apache Tomcat trace back to Sun Microsystems, where it began as the reference implementation for the Java Servlet and JavaServer Pages specifications in the late 1990s.[3] In 1999, Sun donated the codebase to the Apache Software Foundation, leading to the first official release as version 3.0.[3] Over the years, contributions from volunteers at Sun and other organizations have driven its evolution, and in 2005, Tomcat achieved top-level project status within Apache, gaining independence from the broader Jakarta project.[3]
Key features of Apache Tomcat include its support for session management, security configurations, and integration with the Apache HTTP Server via connectors for enhanced performance.[4] As of November 2025, the current development focus is on version 11.0.x, which implements Jakarta Servlet 6.1, JSP 4.0, EL 6.0, WebSocket 2.2, and other related specifications, ensuring compatibility with modern Java enterprise standards.[1] Its modular design and active community make it a popular choice for developers building scalable web solutions without the overhead of a full Jakarta EE application server.[2]
Overview
Definition and Purpose
Apache Tomcat is an open-source software implementation of several key specifications within the Jakarta EE platform, including Jakarta Servlet, Jakarta Pages, Jakarta Expression Language, Jakarta WebSocket, Jakarta Annotations, and Jakarta Authentication, developed and maintained by the Apache Software Foundation.[2][1]
Its primary purpose is to serve as a lightweight servlet container and web server capable of hosting Java-based web applications, particularly those using servlets and JavaServer Pages (JSP), without the need for a full-featured Java EE application server.[2] Tomcat manages the servlet lifecycle—encompassing initialization, service invocation for handling requests, and destruction—while processing HTTP requests and generating dynamic responses to enable interactive web content.[5][6]
Originally initiated at Sun Microsystems as the reference implementation for the Java Servlet and JavaServer Pages specifications, Tomcat was donated to the Apache Software Foundation in 1999, evolving from an experimental reference tool into a robust, production-ready server widely used for mission-critical deployments.[3][5] This progression reflects the broader shift from Java EE to Jakarta EE under the Eclipse Foundation, with Tomcat 10 and later versions aligning with the renamed specifications.[2]
Role in Java Web Development
Apache Tomcat functions as a lightweight servlet container and web server within the Java ecosystem, implementing core specifications such as Jakarta Servlet and Jakarta Server Pages (JSP) to host and execute Java-based web applications without the full feature set of a complete Jakarta EE application server.[4] This positioning makes it an ideal alternative to heavier full-stack servers like JBoss or WebLogic, particularly for projects that primarily need web-tier capabilities rather than enterprise-level services such as message queuing or transaction management.[7] By focusing on servlet and JSP support, Tomcat enables developers to deploy dynamic web content efficiently while avoiding the resource-intensive overhead associated with broader Jakarta EE compliance.[8]
In web application development, Tomcat is extensively used across development, testing, and production phases for building applications that leverage Model-View-Controller (MVC) frameworks like Spring and Struts.[7] For instance, Spring Boot applications often embed Tomcat as their default server, allowing seamless integration for rapid prototyping and deployment of RESTful services or traditional web apps. Its role extends to facilitating hot-reloading during development, which accelerates iteration cycles, and supports production scaling through clustering for handling increased loads in servlet/JSP environments.[9]
Tomcat integrates effectively with the Apache HTTP Server to optimize content delivery, using connectors such as mod_jk (via the AJP protocol) or mod_proxy for forwarding dynamic requests while the HTTP server manages static assets like images and HTML files.[10] This setup enhances performance by distributing workloads, with mod_jk providing binary protocol efficiency for Java-specific traffic and mod_proxy offering simpler HTTP-based proxying.[11] Such integration points allow Tomcat to complement rather than replace traditional web servers in hybrid architectures.
Key advantages of Tomcat include its inherent simplicity, which reduces configuration complexity and startup times compared to full servers; embeddability, enabling it to run within applications without a separate process; and implementation of key specifications from the Jakarta EE Web Profile, such as Servlets, JSP, and WebSocket, ensuring portability for these web-focused standards.[1] Developers opt for Tomcat over alternatives like JBoss or WebLogic in scenarios prioritizing low resource usage and quick deployments, such as microservices or lightweight APIs, where the full enterprise features of those servers would introduce unnecessary bloat.[12]
Architecture and Components
Catalina
Catalina is the servlet container at the heart of Apache Tomcat, implementing the Jakarta Servlet 6.1 specification to manage the lifecycle and execution of servlets within web applications.[1] As the primary engine for processing HTTP requests directed to servlets and JavaServer Pages (JSP), it provides the runtime environment for deploying and running Java-based web components without requiring an external web server for basic operations.[13]
The internal structure of Catalina is organized as a hierarchical set of containers, starting with the Engine as the top-level component that receives requests from connectors and routes them to appropriate child containers. Below the Engine, Hosts represent virtual hosts, each capable of hosting multiple web applications identified by their network name or IP address. Contexts correspond to individual web applications, encapsulating their resources, servlets, and configuration, while Wrappers manage a single servlet instance, handling its instantiation, initialization, and invocation during request processing.
Lifecycle management in Catalina follows a structured process defined primarily through the server.xml configuration file, where components like the Server, Service, Engine, Host, and Context are declared and nested hierarchically. Startup involves initializing the hierarchy from the outermost Server element downward, loading configurations, creating container instances, and starting listeners; shutdown reverses this process to cleanly release resources. Reloading of web applications is supported via the reloadable attribute on Context elements, which enables automatic detection of changes in class files or web.xml to restart the application without affecting the entire server.
Catalina handles Web Application Archive (WAR) file deployment by automatically unpacking and configuring applications placed in the webapps directory under the CATALINA_BASE path, integrating them into the Host or Context hierarchy as needed.[13] Session management is provided at the Context level through implementations like the StandardManager, which tracks user sessions across requests using cookies or URL rewriting, with configurable persistence options for durability. Request processing occurs via valve processing pipelines associated with each container, where a series of Valve components—such as access loggers or authenticators—intercept and modify requests in sequence before reaching the target servlet.
Coyote
Coyote is the connector component within Apache Tomcat's architecture, serving as the primary interface for handling incoming network communications from clients. It acts as the entry point for requests, receiving and parsing them before forwarding the processed request objects to the Catalina container for further handling.[5][14]
Coyote provides pluggable protocol handlers that support multiple communication protocols, including HTTP/1.1 for standard web requests, HTTP/2 for multiplexed and efficient transfers, AJP/1.3 for integration with web servers like Apache HTTP Server, and HTTPS via integration with SSL/TLS layers.[15][16] The HTTP/1.1 and HTTP/2 support enables Tomcat to operate as a standalone web server, while AJP facilitates reverse proxy setups for load balancing and security. HTTPS is achieved by configuring the connector with secure transport attributes, leveraging Java Secure Socket Extension (JSSE) or the Apache Portable Runtime (APR) for encryption.[17]
At the implementation level, Coyote includes non-blocking I/O options to enhance scalability. The NIO (New I/O) implementation, based on Java's java.nio package, uses selector-based multiplexing to handle multiple connections with fewer threads, reducing resource overhead for high-concurrency scenarios.[15] The APR implementation, requiring the Tomcat Native library, employs native code for even lower latency and better integration with operating system resources, particularly beneficial for SSL/TLS processing and file I/O.[15] These are specified in the connector's protocol attribute, such as org.apache.coyote.http11.Http11NioProtocol for NIO-based HTTP/1.1.[18]
Configuration of Coyote connectors occurs primarily in the server.xml file, where each <Connector> element defines endpoints via attributes like port (default 8080 for HTTP), address for binding to specific interfaces, and endpoint settings for thread management.[15] For SSL/TLS in HTTPS setups, attributes such as SSLEnabled="true", scheme="https", and keystore paths are set, with support for client authentication and cipher suites.[17] Endpoint management involves tuning the poller thread pool for NIO/APR modes to optimize connection acceptance and polling.
Performance optimizations in Coyote focus on efficient resource utilization and request throughput. It employs a configurable thread pool, with minSpareThreads (default 10) ensuring idle threads for quick response and maxThreads (default 200) capping concurrent requests to prevent overload.[15] Keep-alive support, enabled by default with enableLookups="false" and tunable via maxKeepAliveRequests (default 100), allows persistent connections to reduce handshake overhead for multiple requests from the same client.[15] Compression handling is provided through the compression="on" attribute (default threshold 2048 bytes), supporting gzip for response bodies to minimize bandwidth usage.[15] Additionally, Coyote facilitates WebSocket upgrades by handling the HTTP Upgrade header, transitioning connections to the WebSocket protocol without interrupting the flow.[15] These features collectively enable Coyote to manage high-volume traffic while maintaining low latency.[18]
Jasper
Jasper serves as the JavaServer Pages (JSP) engine within Apache Tomcat, responsible for translating JSP pages into equivalent Java servlets and overseeing their compilation and execution to generate dynamic web content.[19] This component ensures compliance with the JSP standard by converting markup, scriptlets, expressions, and tags into executable servlet code that integrates with Tomcat's servlet container.[19]
The compilation process in Jasper begins with parsing the JSP source file to identify structural elements such as directives, declarations, expressions, and custom tags.[20] Following parsing, Jasper generates a corresponding Java source file for a servlet, embedding the static content, dynamic logic, and output buffering mechanisms.[20] This generated source is then compiled into bytecode using a Java compiler like javac, integrated with the application's classpath, and the resulting class file is loaded for execution.[20] To support iterative development, Jasper includes reloading capabilities, automatically detecting changes to JSP files and recompiling them as needed when enabled.[20]
Configuration of Jasper occurs primarily through initialization parameters for the JspServlet in the web.xml deployment descriptor or via context-level settings in server.xml or context.xml.[19] The 'development' parameter, when set to true, activates auto-reload mode, prompting Jasper to monitor and recompile modified JSP pages without requiring a full application restart.[20] Tag libraries are configured by declaring Tag Library Descriptors (TLD files) in web.xml or implicitly via JAR resources, enabling the use of predefined or custom tag sets for modular page development.[19] For expression handling, the 'enablePooling' and 'ieClassId' parameters influence resource management, while EL evaluation is controlled by parameters like 'strictQuoteEscaping' to ensure secure and accurate processing of embedded expressions.[20]
Jasper fully supports the Jakarta Expression Language (EL), allowing developers to embed ${} for immediate value expressions and #{} for deferred method expressions directly in JSP attributes, scriptlets, or template text, with evaluation occurring at request time against scoped variables and beans.[19] Custom tags are handled through the JSP tag extension API, where tag files or handler classes implementing Tag or SimpleTag interfaces process attributes, body content, and iteration logic, promoting reusable components without inline Java code.[19]
In line with the Jakarta Pages specification, the latest iteration of Jasper 2 in Tomcat 11.0 implements Jakarta Pages 4.0, providing enhanced performance through optimizations like background compilation and reduced memory footprint during page processing.[19] It efficiently manages static includes via the <%@ include file="..." %> directive, merging the referenced content into the JSP at compile time for a single servlet output.[20] For error handling, Jasper routes JSP-specific exceptions, such as translation or compilation errors, to custom error pages defined in web.xml using elements with exception-type or status-code mappings, ensuring consistent user-facing responses.[19]
Clustering and High Availability
Apache Tomcat provides built-in support for clustering to enable session replication, distributed deployment, and high availability for web applications. The clustering implementation relies on the Apache Tribes framework for inter-node communication, allowing multiple Tomcat instances to form a logical cluster where changes on one node, such as session updates, are propagated to others. This setup ensures that applications remain resilient to node failures by replicating state across the cluster, supporting failover without data loss for users.[21]
Session replication in Tomcat clustering handles stateful applications by synchronizing HTTP session data between nodes. The DeltaManager performs all-to-all replication, sending only the deltas (changes) in session attributes to every other node in the cluster, which is efficient for small to medium-sized clusters but can introduce network overhead in larger ones. In contrast, the BackupManager replicates the full session state to a single backup node designated for each primary node, reducing multicast traffic and scaling better for bigger deployments while still enabling failover. Applications using stateless sessions, which do not rely on server-side state, require no replication and can distribute load evenly without sticky session routing.[22][23]
High availability is achieved through automatic node discovery, failover mechanisms, and integration with load balancers. Nodes discover each other dynamically using multicast via the Tribes membership service, which broadcasts heartbeat messages to maintain cluster membership and detect failures; alternatively, static membership can be configured for environments where multicast is unavailable, such as certain cloud or virtualized networks. Upon node failure, the cluster redirects traffic to healthy nodes, with session data restored from replicas to support seamless failover. For load balancing, Tomcat integrates with the Apache HTTP Server using the mod_jk connector, which supports sticky sessions to route user requests to the same node based on session ID, or the mod_cluster module for dynamic node management and advanced balancing algorithms that advertise node health to the balancer.[24][22][25]
Configuration for clustering is primarily managed through the <Cluster> element in the server.xml file, which defines the channel for communication, membership service, and replication manager. The channel, powered by Tribes, handles message transport over TCP or UDP, with senders and receivers configured for reliable delivery; for example, the multicast sender enables broadcasting to all nodes. The membership service specifies discovery attributes like multicast address (default 228.0.0.4) and port (45564), while the manager (DeltaManager or BackupManager) is nested within the cluster element to control replication behavior. Additionally, farm deployment allows cluster-wide WAR file distribution by placing applications in the webapps directory on one node, after which the FarmWarDeployer replicates them to all others via the cluster channel, ensuring consistent deployments without manual intervention on each instance. A sample configuration might include:
xml
<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="8">
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"/>
<Channel className="org.apache.catalina.tribes.group.GroupChannel">
<Membership className="org.apache.catalina.tribes.membership.McastService"
address="228.0.0.4"
port="45564"
frequency="500"
autoBind="false"/>
<Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="4000"
autoBind="auto"
selectorTimeout="5000"
maxThreads="6"/>
<Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.nio.PooledSender"/>
</Sender>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
</Channel>
<Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
filter=""/>
<Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/>
<Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
readOnly="false"/>
</Cluster>
<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="8">
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"/>
<Channel className="org.apache.catalina.tribes.group.GroupChannel">
<Membership className="org.apache.catalina.tribes.membership.McastService"
address="228.0.0.4"
port="45564"
frequency="500"
autoBind="false"/>
<Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="4000"
autoBind="auto"
selectorTimeout="5000"
maxThreads="6"/>
<Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.nio.PooledSender"/>
</Sender>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
</Channel>
<Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
filter=""/>
<Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/>
<Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
readOnly="false"/>
</Cluster>
This setup requires enabling the distributable directive in the web application's web.xml to activate replication.[21][22]
Despite its capabilities, Tomcat clustering has limitations that influence its suitability. DeltaManager's all-to-all model can lead to high CPU and network usage in clusters exceeding 4-6 nodes, making BackupManager preferable for scalability, though it risks single points of failure if backups overlap. Multicast discovery may fail in firewalled or multi-tenant environments, necessitating static or DNS-based alternatives. Best practices include using sticky sessions with mod_jk to minimize replication traffic, avoiding replication of large session objects (e.g., by storing them externally in a database), and combining Tomcat clustering with an external load balancer like Apache HTTP Server for production high availability rather than relying solely on built-in multicast for node management. Monitoring tools should track cluster membership and replication latency to detect issues early, and applications should be designed to tolerate occasional session ID changes during failover when sticky sessions are disabled.[23][22][24]
Features
Core Capabilities
Apache Tomcat excels in web application deployment by supporting Web Application Archive (WAR) files as the standard packaging format. Users can deploy applications by placing WAR files in the designated webapps directory, where Tomcat automatically unpacks and initializes them during startup. For dynamic environments, hot deployment is facilitated through the autoDeploy attribute in the Host or Engine configuration, enabling Tomcat to monitor the directory for changes and redeploy updated applications without requiring a full server restart. This feature streamlines development and maintenance workflows by allowing seamless updates to running applications.
Context management in Tomcat provides fine-grained control over individual web applications, represented by the Context element in server.xml or context.xml files. This allows administrators to specify unique paths, loader configurations, and resource bindings for each application, ensuring isolation and customization. For instance, contexts can define welcome files, error pages, and security constraints tailored to specific deployments, enhancing modularity in multi-application setups.
Session management is a cornerstone of Tomcat's functionality, adhering to the HTTP session protocol with default support for cookies to maintain session identifiers across requests. When cookies are unavailable or disabled—configurable via the useCookies attribute—Tomcat employs URL rewriting to append session IDs to outgoing URLs, preserving state without client-side storage. Persistence options further extend reliability: the StandardManager saves sessions to a local file for recovery after server restarts, while the PersistentManager integrates with databases or custom stores for distributed or durable session handling.
Tomcat's logging infrastructure relies on JULI, a tailored fork of java.util.logging that offers robust file rotation, asynchronous handling, and per-application log separation to capture internal events like startup sequences and errors. Complementing this, access logs are implemented via the AccessLogValve, which generates detailed records of incoming requests—including timestamps, client IPs, and response codes—in formats compatible with tools like Apache's combined log format for analysis and auditing.
Internationalization support in Tomcat leverages Java's resource bundle mechanism, augmented by the StringManager utility class, which simplifies loading and formatting locale-specific messages from properties files. This enables web applications to dynamically serve content in multiple languages based on client preferences, such as Accept-Language headers, without altering core code. Resource bundles can be organized by package or application context, facilitating scalable multilingual deployments.
As of November 2025, Apache Tomcat version 11.0 achieves compliance with the Jakarta EE 11 web profile, implementing specifications like Servlet 6.1 and JSP 4.0 to support contemporary Java enterprise web development. Additionally, virtual hosting capabilities allow a single Tomcat instance to manage multiple domains through the Host element, mapping distinct network names to separate web application sets while sharing underlying resources efficiently. These features collectively empower Tomcat as a versatile platform for hosting diverse web applications.[26]
Apache Tomcat provides robust security mechanisms through its Realm implementations, which serve as a database for usernames, passwords, and roles to enable container-managed authentication. The JDBC Realm, implemented as DataSourceRealm, connects to relational databases via JNDI DataSources for user lookups, supporting SQL queries to verify credentials and retrieve roles. Similarly, the JNDI Realm interfaces with LDAP directories using JNDI providers to authenticate users and fetch associated roles from directory services. Role-based access control (RBAC) is integrated into these Realms, allowing administrators to define security constraints in web.xml files that restrict access to resources based on user roles, such as limiting administrative functions to users in an "admin" role.[27][28]
To mitigate cross-site request forgery (CSRF) attacks, Tomcat includes the CsrfPreventionFilter, which generates nonces stored in sessions and validates them on state-changing requests, rejecting invalid or missing tokens. For REST APIs, the RestCsrfPreventionFilter enforces CSRF protection via custom headers like X-CSRF-Token, ensuring modifying requests (e.g., POST, PUT) include valid nonces without affecting GET requests.
On the performance front, Tomcat supports efficient database connectivity through integration with Apache Commons DBCP for connection pooling, configurable via JNDI resources in server.xml to reuse connections and reduce overhead in high-load environments. Caching mechanisms include a built-in static resource cache in the Resources element, which stores frequently accessed files like images and scripts to minimize disk I/O, with configurable size limits up to several MiB for optimal memory usage. GZIP compression is enabled at the HTTP Connector level, automatically compressing responses for supported MIME types (e.g., text/html, application/javascript) when clients indicate acceptance via Accept-Encoding headers, potentially reducing bandwidth by 70-80% for compressible content.
Monitoring capabilities are enhanced via Java Management Extensions (JMX), which exposes MBeans for real-time metrics such as request throughput, thread pool usage, and JVM heap statistics, accessible remotely with proper authentication. JMX also facilitates thread dumps through operations like ThreadMXBean.dumpAllThreads, aiding in diagnosing bottlenecks or deadlocks without server restarts.
As of 2025, Tomcat 11 includes full support for TLS 1.3 in its SSL/TLS configuration, leveraging Java's built-in providers for improved security and performance over prior protocols. HTTP/2 server push is available as an optional feature in the HTTP/2 connector, allowing proactive resource delivery to reduce latency, though it requires explicit enabling to avoid compatibility issues. Recent versions (10 and above) address key vulnerabilities, such as CVE-2025-24813 (remote code execution via partial PUT uploads) and CVE-2025-31650 (DoS through HTTP priority manipulation), with mitigations including stricter input validation and protocol handling updates.[29][30]
Best practices for enhancing security and performance include implementing rate limiting with the RateLimitFilter to cap requests per IP, preventing DoS attacks by enforcing thresholds like 100 requests per minute. Adding secure headers via the HttpHeaderSecurityFilter enforces policies such as Strict-Transport-Security (HSTS) for HTTPS enforcement and X-Content-Type-Options to block MIME sniffing. Common misconfigurations to avoid encompass disabling default web applications, restricting JMX access with strong credentials, and regularly updating to patch CVEs, ensuring minimal exposure in production deployments.[31]
Deployment and Configuration
Installation and Setup
Apache Tomcat installation begins with downloading the software from the official Apache Tomcat website. Binary distributions, suitable for most users, are provided in formats such as ZIP for Windows and TAR.GZ for Unix-like systems, along with a dedicated Windows Service Installer executable. Source code distributions are available for compilation from scratch using Apache Ant and a compatible JDK. As of November 2025, the latest stable release is version 11.0.14.[32][2]
A key prerequisite for running Tomcat 11 is a Java Development Kit (JDK) version 17 or later, as it implements Jakarta EE 10 specifications that require this minimum. Tomcat itself has minimal hardware demands and can operate on systems with as little as 256 MB of RAM for basic testing, though production environments typically allocate 1 GB or more depending on application load.
Windows: The recommended method is using the 64-bit or 32-bit Windows Service Installer (.exe file), which automates extraction to a directory like C:\Program Files\Apache Software Foundation\Tomcat 11.0 and registers Tomcat as a Windows service for automatic startup. Alternatively, download the ZIP archive, extract it to a directory, and manually configure it as a service using the service.bat install script in the bin folder.[33][32]
Linux: Download the TAR.GZ binary, extract it to a directory such as /opt/tomcat, and set ownership to a dedicated non-root user (e.g., tomcat) for security. To run as a system service, create a systemd unit file in /etc/systemd/system/tomcat.service referencing the installation path, or use the provided startup.sh script in the bin directory for manual starts. Ensure executable permissions with chmod +x bin/*.sh.[34]
macOS: Tomcat can be installed via Homebrew package manager by running brew install tomcat, which handles dependencies and places files in /opt/homebrew/Cellar/tomcat. For manual installation, download the TAR.GZ, extract to /usr/local/tomcat, and launch using the bin/startup.sh script. Homebrew integration simplifies updates and service management.[34]
Initial Setup and Environment Variables
After extraction or installation, configure essential environment variables. Set JAVA_HOME to the root directory of the JDK installation (e.g., /usr/lib/jvm/java-17-openjdk on Linux or C:\Program Files\Eclipse Adoptium\jdk-17.0.12.7-hotspot on Windows). Define CATALINA_HOME as the Tomcat base directory (e.g., /opt/tomcat), and optionally CATALINA_BASE for multi-instance setups pointing to a separate configuration directory. These variables ensure the startup scripts locate the Java runtime and Tomcat files correctly; they can be set system-wide or in the shell profile (e.g., .bashrc).[34]
To start Tomcat, navigate to the bin directory and execute startup.sh (or startup.bat on Windows), which launches the server on the default HTTP port 8080. For foreground debugging, use catalina.sh run. Shutdown is handled via shutdown.sh or shutdown.bat.[34]
Verification
Successful installation is verified by opening a web browser and navigating to http://localhost:8080, where the default Tomcat welcome page should display, confirming the server is running and serving content. The Manager application, accessible at http://localhost:8080/manager/html, provides tools for deploying and managing web applications but requires initial configuration in conf/tomcat-users.xml to define a user with manager-gui role for authentication. If the welcome page loads without errors, the basic setup is complete.
Basic Configuration
Apache Tomcat's basic configuration is managed through several XML files located in the $CATALINA_BASE/conf directory, allowing administrators to customize server behavior, ports, resources, and security settings without recompiling the software.[35] The primary file, server.xml, defines the overall structure of the Tomcat instance, including connectors for incoming requests, engines for processing, and hosts for virtual hosting.[36] By default, Tomcat configures an HTTP/1.1 connector on port 8080 for non-secure traffic, while the HTTPS connector on port 8443 is provided but commented out in the default installation to require explicit setup.[31] Additionally, server.xml includes a shutdown port on 8005, which listens for the "SHUTDOWN" command to gracefully stop the server; this port can be disabled by setting it to -1 for enhanced security.[36]
The web.xml file in the conf directory serves as the global deployment descriptor, establishing default servlet mappings, MIME types, welcome files, and error pages that apply to all web applications unless overridden in individual application web.xml files.[37] For example, it defines the default servlet for serving static content and sets the session timeout to 30 minutes.[37] Context-specific configurations, particularly for JNDI resources like databases or mail sessions, are handled in context.xml files, which can be placed in the application's META-INF directory or in conf/Catalina/[hostname]/[context].xml to bind resources to specific web applications.[38] These resources are declared using elements within a tag, enabling lookup via JNDI without hardcoding connection details in application code.[38]
Common runtime adjustments include setting JVM parameters through the CATALINA_OPTS environment variable, such as memory allocation with options like -Xms256m -Xmx1024m to optimize heap size based on workload demands.[39] User authentication and roles are configured in tomcat-users.xml, which populates the default UserDatabaseRealm; administrators add elements with usernames, encrypted passwords, and roles like "manager-gui" for accessing administrative interfaces.[28] For instance, the default file includes a sample user with role "tomcat" for basic access.[28]
Application deployment involves defining elements in server.xml or dedicated context files to specify the document base, path, and reloadable status for web applications.[37] Valves, such as the AccessLogValve for request logging, and listeners, like the JspMonitor for JSP compilation monitoring, can be nested within these Context or Host elements to intercept requests or respond to lifecycle events.[37][40] This setup allows fine-grained control over application behavior, such as enabling automatic reloading by setting reloadable="true".[37]
Logging in Tomcat defaults to the Java Util Logging (JUL) framework via the JULI implementation, with configuration managed in conf/logging.properties to set log levels, handlers, and formats for components like Catalina and Coyote.[41] For more advanced logging, administrators can integrate Apache Log4j by replacing JULI with Log4j jars and configuring a log4j2.xml file, though this requires careful dependency management to avoid conflicts.[41] Logs are typically written to the logs directory, with catalina.out capturing stdout/stderr by default.[41]
History and Versions
Development Origins
Apache Tomcat originated in late 1998 at Sun Microsystems as an open-source reference implementation for the Java Servlet and JavaServer Pages (JSP) specifications, developed primarily by software architect James Duncan Davidson to provide a lightweight servlet container.[42][43] This effort addressed the need for a robust, standalone engine to execute servlets and JSPs independently of heavier application servers, building on earlier work but marking a fresh start separate from the existing Apache JServ servlet engine, which relied on a different architecture for integrating Java components with the Apache HTTP Server.[44] Tomcat's design emphasized modularity and ease of integration, positioning it as a direct successor to JServ while introducing a complete rewrite compliant with Servlet API 2.2 and JSP 1.1.[45]
In 1999, Sun Microsystems donated the Tomcat codebase to the Apache Software Foundation as part of the newly formed Jakarta Project, which aimed to foster Java-based web technologies under open governance.[3] Early development involved contributions from Sun volunteers and the broader community, with internal versions 1.x and 2.x tested at Sun before the project's transition to Apache oversight.[46] The first official Apache release, Tomcat 3.0, arrived in 1999, establishing it as the reference implementation within the Jakarta ecosystem and enabling widespread adoption for servlet and JSP development.[47] Concurrently, Davidson created the Apache Ant build tool in 1999 specifically to streamline Tomcat's compilation and packaging, replacing inconsistent make-based systems and becoming a standard for Java projects.[48][49]
Subsequent early releases through the 3.x series refined core functionality, focusing on stability, performance, and compatibility with evolving Java standards, while solidifying Tomcat's role in the Apache portfolio.[3] By 2005, Tomcat had matured sufficiently to graduate from the Jakarta subproject umbrella, becoming a standalone top-level Apache project with independent management and oversight.[3] This milestone reflected its growing impact and the community's commitment to its evolution as a foundational web technology.[50]
Release Timeline and Support
Apache Tomcat's release timeline reflects its evolution alongside Java EE and later Jakarta EE specifications, with major versions typically introducing support for updated Servlet, JSP, and related APIs. The project maintains a steady cadence, aligning releases with specification advancements from the Jakarta EE Working Group. As of November 2025, three major branches—9.x, 10.x, and 11.x—remain actively supported, while older versions like 8.5.x reached end-of-life in 2024.[1][51]
The following table summarizes key major versions, their initial stable release dates, and primary specifications supported:
| Version | Initial Release Date | Key Specifications Supported |
|---|
| 4.x | September 2002 | Servlet 2.3, JSP 1.2 |
| 5.x | December 2004 | Servlet 2.4, JSP 2.0, JSTL 1.1 |
| 6.x | October 2006 | Servlet 2.5, JSP 2.1 |
| 7.x | January 2011 | Servlet 3.0, JSP 2.2, EL 2.2 |
| 8.x | February 2014 | Servlet 3.1, JSP 2.3, EL 3.0 (for 8.5.x branch) |
| 9.x | October 2017 | Servlet 4.0, JSP 2.3, EL 3.0, WebSocket 1.1, JASPIC 1.1 |
| 10.x | December 2020 | Jakarta Servlet 5.0, Jakarta Pages 3.0, Jakarta EL 4.0 |
| 11.x | October 2024 | Jakarta Servlet 6.1, Jakarta Pages 4.0, Jakarta EL 6.0, WebSocket 2.2 (aligned with Jakarta EE 11) |
javax.* packages with jakarta.* to reflect the Eclipse Foundation's stewardship of the specifications post-Oracle's donation of Java EE. This change required application updates for compatibility but enabled alignment with modern Jakarta EE standards. Tomcat 11.x further advanced this by supporting Jakarta EE 11 features.[1]
Apache TomEE
Apache TomEE is a lightweight, certified Jakarta EE application server constructed by extending Apache Tomcat with enterprise Java technologies, primarily through the integration of Apache OpenEJB for support of components like Enterprise JavaBeans (EJB), Contexts and Dependency Injection (CDI), Java Persistence API (JPA), and others.[57][58] This assembly begins with a standard Tomcat distribution and incorporates additional libraries to enable full Jakarta EE compatibility, allowing developers to deploy enterprise applications without the resource demands of heavier servers like WildFly or GlassFish.[57][59]
TomEE offers several variants tailored to different needs: the Plume distribution provides the complete Jakarta EE 10 full platform profile, including advanced features such as full EJB, Java API for RESTful Web Services (JAX-RS), Java Architecture for XML Web Services (JAX-WS), and Java Message Service (JMS); the Web variant supports the Jakarta EE Web Profile, covering essentials like Servlets, JavaServer Pages (JSP), JavaServer Faces (JSF), Java Transaction API (JTA), JPA, CDI, Bean Validation, and EJB Lite; the Plus variant extends the Web Profile with JMS and JAX-WS; and the MicroProfile variant adds Eclipse MicroProfile 6.1 support for cloud-native applications on top of the Web Profile.[60][61] These options ensure certified compliance with Jakarta EE 10 specifications while maintaining Tomcat's simplicity and low footprint.[60]
A key advantage of TomEE is its ability to deliver verified Jakarta EE compatibility—through TCK (Technology Compatibility Kit) certification—for enterprise features without the overhead of a full-fledged application server, making it suitable for microservices, embedded use cases, and traditional web applications.[57][62] Development of TomEE began in 2011 under the leadership of OpenEJB contributors, with the project entering the Apache Software Foundation as a top-level project in April 2012.[59][63] As of September 2025, the latest stable release is version 10.1.2, which is based on Apache Tomcat 10.1.x and requires Java 17 or higher.[61][57][60]
Configuration in TomEE largely inherits Apache Tomcat's mechanisms, such as server.xml for connectors and web.xml for application deployment, but extends them with TomEE-specific files like tomee.xml for global resources and openejb.xml for defining and configuring enterprise beans, data sources, and other OpenEJB-managed components.[64][65] This hybrid approach allows seamless migration from plain Tomcat setups while enabling Jakarta EE-specific deployments through simple additions like bean mappings in openejb-jar.xml descriptors.[66][67]
Development and User Communities
The Apache Tomcat project is governed by a Project Management Committee (PMC) within the Apache Software Foundation, responsible for overseeing development, releases, and community decisions.[2] The development community, comprising global contributors, primarily collaborates via the [email protected] mailing list, where discussions focus on code changes, bug fixes, and feature enhancements.[68] Issue tracking and bug reporting occur through Apache's JIRA system, enabling developers to submit, review, and resolve tasks in a structured manner. As of 2025, the project maintains 50 active committers who handle code integration and maintenance.[69]
Contributions to Tomcat follow open-source guidelines emphasizing quality and collaboration, with prospective developers encouraged to start by subscribing to mailing lists, reporting issues via JIRA, or submitting patches.[70] Code submissions must adhere to Tomcat's coding conventions, which prioritize standard Java formatting—such as consistent indentation, brace placement, and naming—for readability and maintainability.[71] All contributions require accompanying unit and integration tests to verify functionality and prevent regressions, ensuring robust coverage before integration.[71] The release process culminates in a community vote on proposed artifacts, using Apache's standard +1 (approve), 0 (neutral), and -1 (reject) system, where at least three PMC members must vote +1 for approval, typically over a 72-hour period.[72][73]
To facilitate broader participation, Tomcat provides a read-only Git mirror on GitHub, allowing developers to clone, review, and fork the repository while official changes occur via Apache's Git setup.[74] This setup supports modern workflows without altering the project's core Subversion-to-Git migration structure.
User communities form a vital support network for Tomcat adopters, with the [email protected] mailing list serving as the primary forum for troubleshooting, configuration advice, and general inquiries.[68] On Stack Overflow, the 'tomcat' tag remains highly active in 2025, hosting over 50,000 questions and ongoing discussions on deployment, performance, and integration issues, reflecting its enduring popularity among Java developers.[75] Tomcat also engages users through ApacheCon, the foundation's annual conference, featuring dedicated tracks with sessions on topics like security hardening, performance tuning, and upcoming features.[76]