What is Docker Debug and what problem does it solve?

Table of Contents

The docker debug is a new command introduced in Docker Desktop 4.27.0. It allows you to open a debug shell into any container or image. The command aims to provide a more comprehensive ecosystem of debugging tools and is seen as a crucial part of the Docker experience, not just a single CLI command

Docker Debug is a new tool to speed up the debugging process. Docker Debug is a tool designed to improve the troubleshooting process in Docker.

Please note that Docker Debug requires a Pro, Team, or Business subscription. You must sign in to use this command.

What problem does it solve?

One of the main problems it tackles is the difficulty in debugging running and stopping containers. Docker Debug allows developers to join the execution context of a target container or create a temporary execution context for stopped containers, enabling them to investigate the containers.

Docker Debug also improves the shell environment for users, making it user-friendly and efficient. It includes features such as a descriptive prompt, auto-detection of the shell the user is using, persistent history across sessions, and a Nix-based package manager for adding tools as needed.

Additionally, Docker Debug helps with the issue of containers exiting unexpectedly, which previously made debugging impossible at that point.

By addressing these issues, Docker Debug enhances the usability of Docker and makes it easier for users to troubleshoot their applications.

It addresses several key issues:

The inability to effectively debug running and stopped containers. Docker Debug allows users to join the execution context of a target container or create a temporary execution context for stopped containers, enabling them to investigate the containers.
Difficulties in using docker exec command, which only works for containers that ship with a shell and doesn’t work for stopped containers.
The need for a user-friendly and efficient shell environment, which Docker Debug aims to provide. This includes features such as a descriptive prompt, auto-detection of the shell the user is using, persistent history across sessions, and a nix-based package manager for adding tools as needed.
The problem of containers exiting unexpectedly, which makes debugging impossible at that point.

By addressing these issues, Docker Debug enhances the usability of Docker and makes it easier for users to troubleshoot their applications⁠.

Whos’ this for?

Docker Debug is primarily targeted at software developers and IT professionals who work with containerized applications, especially those using Docker for development and deployment. Here’s a breakdown of who would benefit most:

Developers:

Building and deploying containerized applications
Debugging issues within running or stopped containers
Investigating runtime behavior and troubleshooting problems
Simplifying the debugging workflow and streamlining development cycles

IT professionals:

Maintaining and managing containerized environments
Diagnosing and fixing problems in production deployments
Analyzing container performance and resource utilization
Understanding the internals of containerized applications

While Docker Debug is currently in beta and limited to Pro subscribers, its potential benefits extend beyond these primary groups. Anyone who interacts with containerized applications, including system administrators and DevOps engineers, can benefit from its enhanced debugging capabilities and efficient shell environment.

Getting Started

Ensure that you have Docker Desktop 4.27.0+ installed on your computer.
Verifying if the docker debug command is working correctly

docker debug --help


Usage:  docker debug [OPTIONS] {CONTAINER|IMAGE}

Get an enhanced shell with additional tools into any container or image

Options:
  -c, --command string   Evaluate the specified commands instead, passing additional positional arguments through
                         $argv.
      --host string      Daemon docker socket to connect to. E.g.: 'ssh://root@example.org',
                         'unix:///some/path/docker.sock'
      --shell shell      Select a shell. Supported: "bash", "fish", "zsh", "auto". (default auto)
      --version          Display version of the docker-debug plugin

Running Docker Debug for Docker Images

The docker debug command requires container or image name as command-line argument. If you don’t have any container up and running or even if you don’t have any shell available in the running container, Docker Debug helps you to get access to the container shell.

I assume you just installed Docker Desktop 4.27.0 and right now you don’t have any image or container running on your system. Let’s jump into the Nginx image directly.

docker debug nginx
Pulling image, this might take a moment...
0.0.22: Pulling from docker/desktop-docker-debug-service
10c7e62bcff5: Pull complete
Digest: sha256:60b0227c4304f2d703255448aba2863c9a97e21ad0233514de3c7f200904869f
Status: Downloaded newer image for docker/desktop-docker-debug-service:0.0.22
latest: Pulling from library/nginx
a5573528b1f0: Pull complete
8897d65c8417: Pull complete
fbc138d1d206: Pull complete
06f386eb9182: Pull complete
aeb2f3db77c3: Pull complete
64fb762834ec: Pull complete
e5a7e61f6ff4: Pull complete
Digest: sha256:4c0fdaa8b6341bfdeca5f18f7837462c80cff90527ee35ef185571e1c327beac
Status: Downloaded newer image for nginx:latest
         ▄
     ▄ ▄ ▄  ▀▄▀
   ▄ ▄ ▄ ▄ ▄▇▀  █▀▄ █▀█ █▀▀ █▄▀ █▀▀ █▀█
  ▀████████▀    █▄▀ █▄█ █▄▄ █ █ ██▄ █▀▄
   ▀█████▀                        DEBUG

Builtin commands:
- install [tool1] [tool2] ...    Add Nix packages from: https://search.nixos.org/packages
- uninstall [tool1] [tool2] ...  Uninstall NixOS package(s).
- entrypoint                     Print/lint/run the entrypoint.
- builtins                       Show builtin commands.

Checks:
✓ distro:            Debian GNU/Linux 12 (bookworm)
✓ entrypoint linter: no errors (run 'entrypoint' for details)

Note: This is a sandbox shell. All changes will not affect the actual image.
                                                                                                   Version: 0.0.22 (BETA)
root@6c7be49d2a11 / [nginx:latest]
docker >

Inspect the entrypoint

docker > entrypoint
Understand how ENTRYPOINT/CMD work and if they are set correctly.
From CMD in Dockerfile:
 ['nginx', '-g', 'daemon off;']

From ENTRYPOINT in Dockerfile:
 ['/docker-entrypoint.sh']

By default, any container from this image will be started with following command:

/docker-entrypoint.sh nginx -g daemon off;

path: /docker-entrypoint.sh
args: nginx -g daemon off;
cwd:
PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Lint results:
 PASS: '/docker-entrypoint.sh' found
 PASS: no mixing of shell and exec form
 PASS: no double use of shell form

Docs:
- https://docs.docker.com/engine/reference/builder/#cmd
- https://docs.docker.com/engine/reference/builder/#entrypoint
- https://docs.docker.com/engine/reference/builder/#understand-how-cmd-and-entrypoint-interact
root@6c7be49d2a11 / [nginx:latest]

Viewing all builtin commands

builtins
A docker debugging toolbox.                                                                                        0.0.22

Builtin commands:
- install [tool1] [tool2] ...    Add Nix packages from: https://search.nixos.org/packages
- uninstall [tool1] [tool2] ...  Uninstall NixOS package(s).
- entrypoint                     Print/lint/run the entrypoint.
- builtins                       Show builtin commands.

Note: This is a sandbox shell. All changes will not affect the actual image.
                                                                                                   Version: 0.0.22 (BETA)
root@6c7be49d2a11 / [nginx:latest]

Installing NIXOS Packages

install crossplane
Tip: You can install any package available at: https://search.nixos.org/packages.
[2024-01-22T07:13:47.863328585Z][W] tcp keep alive: request failed (Not Found): 404
[2024-01-22T07:13:52.866284045Z][W] tcp keep alive: request failed (Not Found): 404
installing 'crossplane-0.5.8'
these 2 paths will be fetched (0.07 MiB download, 0.26 MiB unpacked):
  /nix/store/dnyyy0nbr9ybyh6b49b450arp3d4zgnq-python3.10-crossplane-0.5.8
  /nix/store/ah81s4zhrdiz24avnfj92jw440kxy7f0-python3.10-crossplane-0.5.8-dist
copying path '/nix/store/dnyyy0nbr9ybyh6b49b450arp3d4zgnq-python3.10-crossplane-0.5.8' from 'https://cache.nixos.org'...
copying path '/nix/store/ah81s4zhrdiz24avnfj92jw440kxy7f0-python3.10-crossplane-0.5.8-dist' from 'https://cache.nixos.org'...
building '/nix/store/ryyfmaqkmy80333cprzipb8v82ghl5nf-user-environment.drv'...
root@6c7be49d2a11 / [nginx:latest]

Displaying the content of a file inside Nginx

docker > bash -c "cat /usr/share/nginx/html/index.html"
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>
root@6c7be49d2a11 / [nginx:latest]
docker >

Tools available in Docker Debug

There are a number of tools that are made available. They don’t modify your container but just shipped with the CLI.

The vim tool

docker > vim
root@6c7be49d2a11 / [nginx:latest]
docker > vi hello
root@6c7be49d2a11 / [nginx:latest]
docker > ls
bin   dev                  docker-entrypoint.sh  hello  lib    mnt  opt   root  sbin  sys  usr
boot  docker-entrypoint.d  etc                   home   media  nix  proc  run   srv   tmp  var
root@6c7be49d2a11 / [nginx:latest]
docker >

The Htop Tool

Which tool

which vim
/nix/var/nix/profiles/default/bin/vim
root@6c7be49d2a11 / [nginx:latest]

Forwarding the port temporarily

root@6c7be49d2a11 / [nginx:latest]
docker > forward --port 81:80 nginx
2024/01/22 09:54:02 [notice] 59#59: using the "epoll" event method
2024/01/22 09:54:02 [notice] 59#59: nginx/1.25.3
2024/01/22 09:54:02 [notice] 59#59: built by gcc 12.2.0 (Debian 12.2.0-14)
2024/01/22 09:54:02 [notice] 59#59: OS: Linux 6.6.12-linuxkit
2024/01/22 09:54:02 [notice] 59#59: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2024/01/22 09:54:02 [notice] 64#64: start worker processes
2024/01/22 09:54:02 [notice] 64#64: start worker process 65
2024/01/22 09:54:02 [notice] 64#64: start worker process 66
2024/01/22 09:54:02 [notice] 64#64: start worker process 67
2024/01/22 09:54:02 [notice] 64#64: start worker process 68
2024/01/22 09:54:02 [notice] 64#64: start worker process 69
2024/01/22 09:54:02 [notice] 64#64: start worker process 70
2024/01/22 09:54:02 [notice] 64#64: start worker process 71
2024/01/22 09:54:02 [notice] 64#64: start worker process 72

Running Docker Debug for the running containers

docker run -d -p 6379:6379 redis

docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS                    NAMES
a1ce95fc8430   redis     "docker-entrypoint.s…"   26 seconds ago   Up 26 seconds   0.0.0.0:6379->6379/tcp   eloquent_hamilton

docker debug eloquent_hamilton
         ▄
     ▄ ▄ ▄  ▀▄▀
   ▄ ▄ ▄ ▄ ▄▇▀  █▀▄ █▀█ █▀▀ █▄▀ █▀▀ █▀█
  ▀████████▀    █▄▀ █▄█ █▄▄ █ █ ██▄ █▀▄
   ▀█████▀                        DEBUG

Builtin commands:
- install [tool1] [tool2] ...    Add Nix packages from: https://search.nixos.org/packages
- uninstall [tool1] [tool2] ...  Uninstall NixOS package(s).
- entrypoint                     Print/lint/run the entrypoint.
- builtins                       Show builtin commands.

Checks:
✓ distro:            Debian GNU/Linux 12 (bookworm)
✓ entrypoint linter: no errors (run 'entrypoint' for details)

This is an attach shell, i.e.:
- Any changes to the container filesystem are visible to the container directly.
- The /nix directory is invisible to the actual container.
                                                                                                                           Version: 0.0.22 (BETA)
redis@a1ce95fc8430 /data [eloquent_hamilton]
docker > ps -aef
UID        PID  PPID  C STIME TTY          TIME CMD
redis        1     0  0 10:08 ?        00:00:04 redis-server *:6379
root        47     0  0 10:24 pts/0    00:00:00 /bin/sh
root        54    47  0 10:24 pts/0    00:00:00 bash
redis       57     0  0 10:29 pts/0    00:00:00 /nix/var/nix/profiles/default/bin/zsh -i
redis       69    57  0 10:29 pts/0    00:00:00 ps -aef
redis@a1ce95fc8430 /data [eloquent_hamilton]
docker >

Installing nmap packages

docker > install nmap
Tip: You can install any package available at: https://search.nixos.org/packages.
[2024-01-22T10:36:46.561468511Z][W] tcp keep alive: request failed (Not Found): 404
[2024-01-22T10:36:51.567299097Z][W] tcp keep alive: request failed (Not Found): 404
replacing old 'nmap-7.93'
installing 'nmap-7.93'
redis@a1ce95fc8430 /data [eloquent_hamilton]

To check what ports are opened for scanme.nmap.org, run the following command

docker > nmap -v -A scanme.nmap.org
Starting Nmap 7.93 ( https://nmap.org ) at 2024-01-22 10:38 UTC
NSE: Loaded 155 scripts for scanning.
NSE: Script Pre-scanning.
Initiating NSE at 10:38
Completed NSE at 10:38, 0.00s elapsed
Initiating NSE at 10:38
Completed NSE at 10:38, 0.00s elapsed
Initiating NSE at 10:38
Completed NSE at 10:38, 0.00s elapsed
Initiating Ping Scan at 10:38
Scanning scanme.nmap.org (45.33.32.156) [2 ports]
Completed Ping Scan at 10:38, 0.22s elapsed (1 total hosts)
Initiating Parallel DNS resolution of 1 host. at 10:38
Completed Parallel DNS resolution of 1 host. at 10:38, 0.84s elapsed
Initiating Connect Scan at 10:38
Scanning scanme.nmap.org (45.33.32.156) [1000 ports]
Discovered open port 80/tcp on 45.33.32.156
Discovered open port 22/tcp on 45.33.32.156