Debugging any JVM in a Docker container

Thanks to JAVA_TOOL_OPTIONS variable it’s easy to run any JVM-based Docker image in debug mode. All we have to do is  add environment variable definition „JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005” in docker run or docker-compose.yml and expose port to connect debugger



Docker nowadays (since 1.10, the original pull request is here docker/docker/#17989) adds some security to running containers by wrapping them in both AppArmor (or presumably SELinux on RedHat systems) and seccomp eBPF based syscall filters (here’s a nice article about it). And ptrace is disabled in the default seccomp profile.

$ docker run alpine sh -c 'apk add -U strace && strace echo'
(1/1) Installing strace (4.11-r2)
Executing busybox-1.24.2-r11.trigger
OK: 6 MiB in 12 packages
strace: ptrace(PTRACE_TRACEME, ...): Operation not permitted
+++ exited with 1 +++

Why am I writing about this? Because some JDK tools depend on PTRACE_ATTACH on Linux. One of them is  very useful jmap.

Turning seccomp off (–security-opt seccomp=unconfined) is not recommended, but we can add just this one explicit capability  with –cap-add=SYS_PTRACE.

$ docker run --cap-add=SYS_PTRACE alpine sh -c 'apk add -U strace && strace echo'
(1/1) Installing strace (4.11-r2)
Executing busybox-1.24.2-r11.trigger
OK: 6 MiB in 12 packages
execve("/bin/echo", ["echo"], [/* 5 vars */]) = 0
arch_prctl(ARCH_SET_FS, 0x7feaca3a8b28) = 0
set_tid_address(0x7feaca3a8b60) = 10
mprotect(0x7feaca3a5000, 4096, PROT_READ) = 0
mprotect(0x558c47ec6000, 16384, PROT_READ) = 0
getuid() = 0
write(1, "\n", 1) = 1
exit_group(0) = ?
+++ exited with 0 +++

Docker Compose supports cap_add since version 1.1.0 (2015-02-25).

If you run into an issue with the jmap and jstack from OpenJDK failing with exception java.lang.RuntimeException: unknown CollectedHeap type : class sun.jvm.hotspot.gc_interface.CollectedHeap make sure you install openjdk-debuginfo package (or openjdk-8-dbg or something similiar depending on distro).

Running Linux graphical applications in Docker on Windows with Cygwin/X

Install Babun

Cygwin is a great tool, but not the easiest to install. Babun consists of a pre-configured Cygwin  that does not interfere with existing Cygwin installation.

Download the dist file from, unzip it and run the install.bat script. After a few minutes the application will be installed to the %USERPROFILE%\.babun directory. You can use the /target (or /t)  option to install babun to a custom directory.

Install Cygwin/X

Run pact from babun shell (pact is a babun package manager )

pact install xorg-server xinit xhost

Start the X server

Once the installation has completed, open a Cygwin terminal and run XWin :0 -listen tcp -multiwindow. This will start an X server on Windows machine
with the ability to listen to connections from the network (-listen tcp) and display
each application in its own window (-multiwindow), rather than a single window acting
as a virtual screen to display applications on. Once it’s started, you should see an
„X” icon in Windows tray area.

Run graphical application

fr3nd/xeyes  is a good test to run

// don't forget to change WINDOWS_MACHINE_IP_ADDR!
// 'localhost' obviously won't work from within Docker container
docker run -e DISPLAY=$WINDOWS_MACHINE_IP_ADDR:0 --rm fr3nd/xeyes

Or we can build ourselves image with Firefox using the following Dockerfile as a starting point

FROM centos

RUN yum -y update && yum install -y firefox

CMD /usr/bin/firefox

docker build -t firefox . it and run the container with

docker run -ti --rm -e DISPLAY=$DISPLAY firefox

If all goes well you should see Firefox running from within a Docker container.


If you have issues with authorization you may want to try running the insecure xhost + command to permit access from all machines. See xhost(1) Linux man page.


There are a few different options to run GUI applications inside a Docker container like using SSH with X11 forwarding or VNC.