how to run standalone tomcat 11 service in debug mode

3 min read 24-01-2025

how to run standalone tomcat 11 service in debug mode

Running Tomcat 11 in debug mode allows you to step through your code, inspect variables, and identify the root cause of issues during development. This guide details how to configure and run a standalone Tomcat 11 instance for debugging. This is crucial for efficient troubleshooting and development.

Setting Up Your Tomcat 11 Environment

Before we begin debugging, ensure you have the following:

Java Development Kit (JDK): Tomcat requires a JDK, not just a JRE. Make sure you have it installed and configured correctly. Your JAVA_HOME environment variable should point to your JDK installation directory.
Apache Tomcat 11: Download the appropriate standalone Tomcat 11 distribution from the Apache Tomcat website. Extract the archive to a directory of your choice.
IDE (Optional but Recommended): An Integrated Development Environment (IDE) like IntelliJ IDEA, Eclipse, or NetBeans simplifies debugging. These tools provide visual debuggers and other helpful development features.

Configuring Tomcat 11 for Remote Debugging

Tomcat's default configuration doesn't enable remote debugging. We need to make some adjustments to the catalina.sh (or catalina.bat on Windows) startup script.

Modifying the Catalina Script

Locate the script: Find the catalina.sh file within the bin directory of your Tomcat installation.
Add Debug Options: Open catalina.sh in a text editor. Near the top, add the following lines, replacing <port> with a port number (e.g., 8000) not already in use on your system and <suspend> with either "n" or "y". "y" will suspend the Tomcat startup until a debugger attaches; "n" will start Tomcat immediately.

JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=<suspend>,address=<port>"

Explanation:

-agentlib:jdwp: This tells the JVM to load the Java Debug Wire Protocol agent.
transport=dt_socket: Specifies that the debugger will communicate over a socket.
server=y: Indicates that Tomcat will act as the debug server.
suspend=<suspend>: If "y", Tomcat will wait for a debugger to attach before starting. If "n", Tomcat will start immediately, and you'll need to attach the debugger later.
address=<port>: Defines the port number Tomcat will listen on for debug connections.

Save and restart Tomcat: Save your changes to catalina.sh. Restart Tomcat using the startup.sh script.

Attaching a Debugger

Now that Tomcat is configured, we'll attach a debugger from your IDE.

IntelliJ IDEA Example

Create a Remote Debug Configuration: In IntelliJ IDEA, go to "Run" -> "Edit Configurations...". Click the "+" button and select "Remote".
Configure the Debugger:
- Name: Give your configuration a name (e.g., "Tomcat Remote Debug").
- Host: Enter the IP address or hostname of the machine running Tomcat (usually localhost).
- Port: Enter the port number you specified in catalina.sh (e.g., 8000).
Start Debugging: Click "OK" to save the configuration. Then click the debug button (the bug icon) next to your new configuration.

Now, your IDE will be connected to your running Tomcat instance and you can set breakpoints, step through code, and examine variables.

Eclipse and NetBeans

Similar remote debug configuration options are available in Eclipse and NetBeans. Consult their respective documentation for specific instructions.

Troubleshooting

Port Conflicts: If you get an error indicating the port is already in use, choose a different port in catalina.sh and your IDE configuration.
Firewall Issues: Ensure your firewall allows connections on the debug port.
Incorrect Configuration: Double-check that you've correctly added the JAVA_OPTS line to catalina.sh and that the port numbers match in both the script and your IDE configuration.
Debugger Not Connecting: Verify Tomcat is running and that the suspend option is set appropriately. If suspend=n, ensure you initiate the debug connection after Tomcat has started.

By following these steps, you can successfully run your standalone Tomcat 11 service in debug mode, significantly improving your development workflow and troubleshooting capabilities. Remember to always revert debug-related changes to catalina.sh after debugging is complete for a production-ready environment.