Debug XWiki Remotely in Docker
Steps
To connect an IDE debugger to the JVM that runs XWiki inside the container, start the container with the JDWP agent enabled and publish the debug port. The agent options reach the JVM through the JAVA_OPTS environment variable, which Tomcat passes on when it starts.
- Pick the port the debugger will connect to, for example 5005.
- Start the XWiki container with the agent options in JAVA_OPTS and that port published with -p. The * of address=*:5005 makes the agent listen on every interface of the container, without which the port cannot be reached from the host:
docker run --net=xwiki-nw --name xwiki -p 8080:8080 -p 5005:5005 -v xwiki:/usr/local/xwiki -e DB_USER=xwiki -e DB_PASSWORD=xwiki -e DB_DATABASE=xwiki -e DB_HOST=mysql-xwiki -e JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" xwiki - Check the container output with
docker logs -f xwikifor the lineListening for transport dt_socket at address: 5005, which the JVM prints when the agent is active. - In your IDE, create a remote JVM debug configuration pointing at port 5005 of the Docker host, and attach it to the running instance.
Don't forget to replace xwiki-nw with the name of your Docker network, and the values of the environment variables with your own.
FAQ
Should the JVM wait for the debugger before starting?
Only if you need to debug the startup itself. With suspend=n, as in the example above, XWiki starts normally and you attach the debugger whenever you need it. With suspend=y, the JVM pauses before running XWiki and waits for a debugger to connect.
What can I do once the debugger is attached?
The same as on a local JVM: set breakpoints, inspect variables, step through the code and analyze the runtime behavior of the running XWiki instance.
Are the old -Xdebug and -Xnoagent options still needed?
No. They date back to Java 5 and are obsolete on the Java runtime the image ships, and -Djava.compiler=NONE makes the JVM print an "obsolete and no longer supported" warning on every start. -agentlib:jdwp on its own is enough.
Can I pass other JVM options the same way?
Yes. JAVA_OPTS is the general mechanism for passing JVM options to the JVM running XWiki, the heap size for instance, and it is not specific to debugging. See Environment Variables of the XWiki Docker Image.
