English ∙ 简体中文

docker-debug is an troubleshooting running docker container, which allows you to run a new container in running docker for debugging purpose. The new container will join the pid, network, user, filesystem and ipc namespaces of the target container, so you can use arbitrary trouble-shooting tools without pre-installing them in your production container image.

Install the docker-debug cli

mac brew

brew install zeromake/docker-debug/docker-debug

download binary file

# get latest tag
VERSION=`curl -w '%{url_effective}' -I -L -s -S https://github.com/zeromake/docker-debug/releases/latest -o /dev/null | awk -F/ '{print $NF}'`

# MacOS Intel
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/${VERSION}/docker-debug-darwin-amd64

# MacOS M1
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/${VERSION}/docker-debug-darwin-arm64

# Linux
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/${VERSION}/docker-debug-linux-amd64

chmod +x ./docker-debug
sudo mv docker-debug /usr/local/bin/

# Windows
curl -Lo docker-debug.exe https://github.com/zeromake/docker-debug/releases/download/${VERSION}/docker-debug-windows-amd64.exe

# get latest tag
set VERSION (curl -w '%{url_effective}' -I -L -s -S https://github.com/zeromake/docker-debug/releases/latest -o /dev/null | awk -F/ '{print $NF}')

# MacOS Intel
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/$VERSION/docker-debug-darwin-amd64

# MacOS M1
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/$VERSION/docker-debug-darwin-arm64

# Linux
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/$VERSION/docker-debug-linux-amd64

chmod +x ./docker-debug
sudo mv docker-debug /usr/local/bin/

# Windows
curl -Lo docker-debug.exe https://github.com/zeromake/docker-debug/releases/download/$VERSION/docker-debug-windows-amd64.exe

download the latest binary from the release page and add it to your PATH.

Try it out!

# docker-debug [OPTIONS] CONTAINER COMMAND [ARG...] [flags]
docker-debug CONTAINER COMMAND

# More flags
docker-debug --help

# info
docker-debug info

Clone this repo and:

go build -o docker-debug ./cmd/docker-debug
mv docker-debug /usr/local/bin

docker-debug uses nicolaka/netshoot as the default image to run debug container. You can override the default image with cli flag, or even better, with config file ~/.docker-debug/config.toml

version = "0.7.4"
image = "nicolaka/netshoot:latest"
mount_dir = "/mnt/container"
timeout = 10000000000
config_default = "default"

[config]
  [config.default]
    version = "1.40"
    host = "unix:///var/run/docker.sock"
    tls = false
    cert_dir = ""
    cert_password = ""

• support windows7(Docker Toolbox)
• support windows10
• refactoring code
• add testing
• add changelog
• add README_CN.md
• add brew package
• docker-debug version manage config file
• cli command set mount target container filesystem
• mount volume filesystem
• docker connection config on cli command
• -v cli args support
• docker-debug signal handle smooth exit
• cli command document on readme
• config file document on readme
• add http api and web shell

1. find image docker is has, not has pull the image.
2. find container name is has, not has return error.
3. from customize image runs a new container in the container's namespaces (ipc, pid, network, etc, filesystem) with the STDIN stay open.
4. create and run a exec on new container.
5. Debug in the debug container.
6. then waits for the debug container to exit and do the cleanup.

1. kubectl-debug: docker-debug inspiration is from to this a kubectl debug tool.
2. Docker核心技术与实现原理: docker-debug filesystem is from the blog.
3. docker-engine-api-doc: docker engine api document.

This project exists thanks to all the people who contribute. [Contribute].

Become a financial contributor and help us sustain our community. [Contribute]

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]