how to run standalone tomcat 11 in debug mode

Lussy04

3 min read

·

24-01-2025

1

0

Share

Running Tomcat 11 in debug mode is crucial for developers. It allows you to step through your code, inspect variables, and identify the root cause of issues. This guide provides a comprehensive walkthrough of setting up and using debug mode with a standalone Tomcat 11 instance.

Setting up Tomcat 11 for Debugging

Before you begin, ensure you have a standalone Tomcat 11 installation. Download it from the official Apache Tomcat website if you haven't already.

1. Configure the catalina.sh (or catalina.bat) Script

The key to enabling debug mode lies in modifying the Tomcat startup script. Find your catalina.sh (for Linux/macOS) or catalina.bat (for Windows) file, typically located in the bin directory of your Tomcat installation.

We'll add the following JVM options to enable remote debugging. These options tell the JVM to listen for a debugger connection on a specified port.

For catalina.sh:

CATALINA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 $CATALINA_OPTS"

For catalina.bat:

set CATALINA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 %CATALINA_OPTS%

Let's break down these options:

• -Xdebug: Enables debugging support in the JVM.
• -Xrunjdwp: Specifies the Java Debug Wire Protocol (JDWP) options.
  • transport=dt_socket: Uses the socket transport for communication.
  • server=y: Indicates that the JVM is acting as a debug server.
  • suspend=n: The application starts immediately; it doesn't wait for a debugger to attach. If you use suspend=y, Tomcat will pause until a debugger connects.
  • address=8000: Sets the port number for the debugger to connect to (you can change this to an available port).

2. Start Tomcat

Now, start Tomcat using the startup.sh (or startup.bat) script located in the same bin directory. You should see Tomcat start normally. The JVM is now listening for a debugger connection on port 8000.

Connecting a Debugger

With Tomcat running in debug mode, you need a debugger to connect to it. Popular choices include:

• IntelliJ IDEA: A powerful IDE with excellent debugging capabilities.
• Eclipse: Another robust IDE supporting Java debugging.
• Visual Studio Code: A versatile code editor with debugging extensions.

Connecting Using IntelliJ IDEA (Example)

1. Create a Run/Debug Configuration: In IntelliJ IDEA, go to Run -> Edit Configurations.
2. Add a Remote Configuration: Click the "+" button and select Remote.
3. Configure the Connection:
   • Name: Give it a descriptive name (e.g., "Tomcat 11 Debug").
   • Host: localhost (unless you're debugging a remote Tomcat instance).
   • Port: 8000 (or the port you specified in catalina.sh/catalina.bat).
4. Start Debugging: Click the debug button (the bug icon) to start the debugging session. IntelliJ IDEA will connect to the Tomcat instance. You can now set breakpoints in your code and step through it.

Troubleshooting

• Port Already in Use: If you get an error that the port is already in use, change the address value in the catalina.sh/catalina.bat file to a different available port.
• Connection Refused: Double-check that Tomcat is actually running in debug mode and that the port number in your debugger configuration matches the one in catalina.sh/catalina.bat. Ensure firewalls aren't blocking the connection.
• Debugger Not Attaching: If suspend=y was used, ensure your debugger is attached before Tomcat fully starts.

Conclusion

Running Tomcat 11 in debug mode significantly simplifies troubleshooting and development. By following these steps and choosing your preferred debugging tool, you can efficiently debug your web applications. Remember to revert the changes to catalina.sh/catalina.bat when you're finished debugging to avoid potential performance impacts in a production environment. Always prioritize security and consider the implications of leaving debug mode enabled in a production or publicly accessible system.