Debug mode in Docker for Tomcat and TomEE

Remote debugging is a common practice for troubleshooting issues in software development.

If you are using Tomcat or TomEE with Docker containers as part of your stack you can find various techniques to enable debug capabilities in these types of containers:

1. Create a custom Docker image by extending an existing official one^[1]
2. Extensive customization of CATALINA_OPSTS^[2]

However, both approaches require extra steps in some scenarios. Below I share the simplest method I have used to do remote debugging in Apache Tomcat and Apache TomEE with a Docker image:

$
$ docker run -it -p 8080:8080 -p 8000:8000 -e CATALINA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000" tomcat:9.0.17-jre11

Parameters description:

• docker run
  • Runs a docker container
• -it
  • Enables interactive mode for the container. This allocates a pseudo-tty and keeps STDIN open even if not attached.
• -p 8080:8080 -p 8000:8000
  • Exposes containers port to the docker host
• -e CATALINA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000"
  • Minimum customization for CATALINA_OPTS to enable debug mode, useful for the majority of cases
• tomcat:9.0.17-jre11
  • Image and label from the Docker container we want to run.