DOCSEARCHbyAlgolia
Submit Docs

Apache Tomcat Documentation

repository·main·Indexed 27 days ago

https://github.com/apache/tomcat

An open-source web server implementation of Jakarta EE technologies, including Servlet, JSP, WebSocket, and Expression Language. This documentation covers installation, configuration of the 'stuffed' distribution, Maven and Docker build processes, GraalVM native image compilation, OpenSSL API support via jextract, and server management using catalina.sh and catalina.bat.

Tokens
9.9K
Snippets
17
Records
71
Agent score
86%

What's inside Apache Tomcat

  1. Overview of Apache Tomcat

    main
    Apache Tomcat is an open source implementation of the Jakarta Servlet, Jakarta Pages, Jakarta Expression Language, and Jakarta WebSocket technologies. It is designed to power large-scale, mission-critical web applications and is released under the Apache License version 2.

  2. Build Tomcat Stuffed Native Image

    main

    To run Tomcat in a container as a native image, refer to the official Tomcat documentation for native-image usage (found in docs/graal.html).

    Static Linking Considerations: If the container runtime is different from the build platform, use the --static parameter in the native-image call to link base libraries (requires zlib and glibc static libraries).

    Important Limitation: TLS support is not available with static linking because TLS uses dynamic libraries (SunEC for JSSE and tomcat-native for OpenSSL). If TLS is required, the native image must be built on a platform identical to the target platform.

  3. Get Support and Community Information

    main

    Apache Tomcat provides several community-driven support channels:

    • Community Support: Join the tomcat-users email list for general community assistance.
    • Release Announcements: Subscribe to the tomcat-announce email list to receive information regarding new code releases, bug fixes, security fixes, and general news.
    • Bug Reporting: If you encounter a concrete bug, follow the official instructions at https://tomcat.apache.org/bugreport.html.
    • General Resources: For additional help with running Tomcat, visit the resources page.

  4. Configure Kubernetes Cluster Membership

    main

    When using the Kubernetes cloud clustering membership provider, the pod requires permission to view other pods. In OpenShift, you can grant this permission using the following command:

    oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)

  5. Configure Apache Tomcat for NetBeans IDE

    main

    To use Apache Tomcat as a 'Free-Form Project' in NetBeans (allowing you to edit, build, and debug Tomcat and its unit tests), follow these steps:

    1. Prerequisite: Ensure you can successfully build and run tests using Apache Ant from a command prompt (refer to BUILDING.txt in the Tomcat source root).
    2. Generate Project Files: Run the following Ant target from the Tomcat source root to create the nbproject directory required by NetBeans:
      ant ide-netbeans
    3. Configure Dependencies: NetBeans needs to know the location of Tomcat dependency JARs.
      • If you have a base.path property defined in your build.properties file, NetBeans will detect it.
      • Warning: If base.path is left at its default, you MUST manually define this path in the nb-tomcat-project.properties file.
    4. Open in NetBeans: Open the Tomcat directory in NetBeans. It should be recognized as a Free-Form project and validate the nbproject/project.xml file.

    Important Warnings:

    • Do not use the Project Properties menu in NetBeans. Doing so may cause NetBeans to modify the configuration files and break the integration.
    • If the configuration files are modified/corrupted, you can restore the defaults by running:
      ant ide-netbeans-replace
    • Current NetBeans support does not include components in the modules directory (e.g., tomcat-lite).
    ant ide-netbeans

  6. Build Apache Tomcat Stuffed with Maven

    main

    To build the project using Maven:

    1. Update the Tomcat version number in pom.xml.
    2. Customize Tomcat components in the dependencies to retain only necessary ones (only tomcat-catalina is mandatory).
    3. Add custom Tomcat component sources to the standard Maven build path to include them in the package.

    Run the following command:

    mvn clean; mvn package

  8. Debug an external Tomcat instance in NetBeans

    main

    You can debug an external Tomcat instance (running on the same or a different machine) using the NetBeans Free-Form project, provided the external instance is running the same version of the source code.

    1. Prepare External Tomcat: Start the external Tomcat instance with JVM debugging enabled by adding arguments to JAVA_OPTS. For example:
      -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
    2. Attach NetBeans:
      • In NetBeans, select "attach debugger" from the debug menu.
      • Select the JPDA debugger with the SocketAttach connector and the dt_socket transport.
      • Specify the hostname and port where the Tomcat JVM is listening.
    3. Debug: Once connected, NetBeans will display running threads, allowing you to set breakpoints and inspect the external process.
    -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

  9. Configure GraalVM Native Image reflection and resources

    main

    When compiling Apache Tomcat with GraalVM's native-image compiler for Ahead of Time (AOT) compilation, specific directives are required to ensure reflection and resource files are correctly included in the native executable.

    These directives must be placed in the following directory structure within your JAR: META-INF/native-image/<groupId>/<artifactId>/

    Required configuration files:

    • reflect-config.json: Defines which classes use reflection.
    • resource-config.json: Ensures resource files normally included in a JAR are compiled into the executable image.

  10. Build and Verify Tomcat in NetBeans

    main

    After configuring the project, verify the integration with the following actions in NetBeans:

    1. Clean: Run the Clean project action to ensure the environment is ready.
    2. Build: Run the Build action. This calls the Tomcat deploy build target and should compile source files and create JARs.
    3. Compile Tests:
      • To compile a specific test file, select it and choose the compile action.
      • To ensure all changed test files are handled, use the compileAllTests project action.
    4. Run Tests: Select a unit test class and choose the "run selected file" action.
    5. Debug Tests: Set a breakpoint in a test case and request NetBeans to debug that class. You can then use standard debugging tools (display variables, navigate call stack, step through code).

  11. Add license headers to generated OpenSSL Java files

    main
    Before committing any updated generated files, you must add the required license headers. Use the addlicense.sh script to process all Java source files located in the src/main/java/org/apache/tomcat/util/openssl directory.

  12. Build OpenSSL API support classes using jextract

    main

    To use additional native APIs from OpenSSL or the stdlib, you can build the OpenSSL API support classes using jextract (available in Java 22+).

    1. Download jextract from https://jdk.java.net/jextract/.
    2. Set the JEXTRACT_HOME environment variable to the extracted path.
    3. Determine your system's include paths using gcc -xc -E -v - (e.g., on Fedora, it might be /usr/lib/gcc/x86_64-redhat-linux/14/include).
    4. Update openssl-tomcat.conf with the correct include path.
    5. Run the jextract command using the configuration file to generate a trimmed-down OpenSSL API.
    $JEXTRACT_HOME/bin/jextract @openssl-tomcat.conf openssl.h