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. It’s currently in beta and available to Pro subscribers. 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.
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 debugcommand is working correctly
Copied!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.
Copied!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
Copied!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:
Copied!/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
Copied!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
Copied!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
Copied!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.
1. The vim tool
Copied!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 >
2. The Htop Tool
2. Which tool
Copied!which vim /nix/var/nix/profiles/default/bin/vim root@6c7be49d2a11 / [nginx:latest]
4. Forwarding the port temporarily
Copied!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
5. Running Docker Debug for the running containers
Copied!docker run -d -p 6379:6379 redis
Copied!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
Copied!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 >
5. Installing nmap packages
Copied!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
Copied!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
Leave a Reply