Interactive debugger for Dockerfile, with support for IDEs (VS Code, Emacs, Neovim, etc.)
Interactive debugger for Dockerfile, with support for IDEs (VS Code, Emacs, Neovim, etc.)
[⬇️ Download] [ Command reference] [ Use on IDEs]
buildg is a tool to interactively debug Dockerfile based on BuildKit.
early stage software This is implemented based on BuildKit with some unmerged patches. We're planning to upstream them.
buildg debug /path/to/build/contextThe above command starts an interactive debugger session for debugging the Dockerfile in /path/to/build/context.
For the detailed command refenrece, refer to Command reference.
Debug the following Dockerfile:
FROM ubuntu AS dev
RUN echo hello > /hello
RUN echo world > /world
FROM scratch
COPY --from=dev /hello /
COPY --from=dev /world /Store this Dockerfile to somewhere (e.g. /tmp/ctx/Dockerfile) then run buildg debug.
…Buildg allows visual and interactive debugging of Dockerfile on editors like VS Code, emacs and Neovim. This is provided throgh DAP(Debug Adapter Protocol) supported by editors (official list).
See ./examples/dap/README.md for usage of DAP.
Binaries are available from https://github.com/ktock/buildg/releases
Requirements:
They are included in our release tar buildg-full-<version>-<os>-<arch>.tar.gz but not included in buildg-<version>-<os>-<arch>.tar.gz.
NOTE1: Native execution is supported only on Linux as of now. On other platforms, please run buildg on Linux VM (e.g. Lima, etc)
NOTE2: buildg on IDEs (VS Code, Emacs, Neovim, etc.) requires rootless execution
NOTE3: For troubleshooting rootless mode, please see also the doc provided by BuildKit: https://github.com/moby/buildkit/blob/master/docs/rootless.md#troubleshooting
Go 1.23+ is needed.
$ git clone https://github.com/ktock/buildg
$ cd buildg
$ make
$ sudo make installnerdctl project provides buildg as a subcommand since v0.20.0: https://github.com/containerd/nerdctl/blob/v0.20.0/docs/builder-debug.md
$ nerdctl builder debug /path/to/build/contextYou can run buildg inside Docker.
Images are available at ghcr.io/ktock/buildg.
You need to bind mount the build context to the container.
$ docker run --rm -it --privileged -v /path/to/ctx:/ctx:ro ghcr.io/ktock/buildg:0.4 debug /ctxYou can also build this container image on the buildg repo.
$ docker build -t buildg .
$ docker run --rm -it --privileged -v /path/to/ctx:/ctx:ro buildg debug /ctxYou can also use bake command by Docker Buildx to build the container:
docker buildx bake --set image-local.tags=buildgTip: the volume at the buildg root enables to reuse cache among invocations and can speed up 2nd-time debugging.
docker run --rm -it --privileged \ -v buildg-cache:/var/lib/buildg \ -v /path/to/ctx:/ctx:ro \ buildg debug /ctx
Debugging a large and complex Dockerfile isn't easy and can take a long time. The goal of buildg is to solve it by providing a way to inspect the detailed execution state of a Dockerfile in an interactive and easy-to-use UI/UX.
BuildKit project has been working on better debugging support (e.g. https://github.com/moby/buildkit/pull/2813, https://github.com/moby/buildkit/issues/1472, https://github.com/moby/buildkit/issues/749). Leveraging the generic features added through the work, this project implements a PoC for providing easy UI/UX to debug Dockerfile.
buildctl by BuildKit : has debug commands to inspect buildkitd, LLB, etc. but no interactive debugging for builds.Debug a build. This starts building the specified Dockerfile and launches a debug session.
Usage: buildg debug [OPTIONS] CONTEXT
Flags:
--file value, -f value: Name of the Dockerfile--target value: Target build stage to build.--build-arg value: Build-time variables--image value: Image to use for debugging stage. Specify --image flag for exec command in debug shell when use this image. See ./docs/bringing-image.md for details.--secret value : Secret value exposed to the build. Format: id=secretname,src=filepath--ssh value : Allow forwarding SSH agent to the build. Format: default|<id>[=<socket>|<key>[,<key>]]--cache-from value: Import build cache from the specified location. e.g. user/app:cache, type=local,src=path/to/dir (see ./docs/cache-from.md)--cache-reuse : Reuse locally cached previous results (enabled by default). Sharing cache among parallel buildg processes isn't supported as of now.Prune cache
Usage: buildg prune [OPTIONS]
Flags:
--all: Prune including internal/frontend referencesShow disk usage information
Usage: buildg du
Serve Debug Adapter Protocol (DAP) via stdio.
Should be called from editors.
See ./examples/dap/README.md for usage of DAP.
Usage: buildg dap serve [OPTIONS]
Flags:
--log-file value: Path to the file to output logsPrune DAP cache.
See ./examples/dap/README.md for usage of DAP.
Usage: buildg dap prune [OPTIONS]
Flags:
--all: Prune including internal/frontend referencesShow disk usage of DAP cache
See ./examples/dap/README.md for usage of DAP.
Usage: buildg dap du
Set a breakpoint.
Alias: b
Usage: break BREAKPOINT
The following value can be set as a BREAKPOINT.
on-fail: breaks on step that returns an errorShow breakpoints key-value pairs.
Alias: bp
Usage: breakpoints
Clear a breakpoint. Specify breakpoint key.
Usage: clear BREAKPOINT_KEY
BREAKPOINT_KEY is the key of a breakpoint which is printed when executing breakpoints command.
Clear all breakpoints.
Usage: clearall
Proceed to the next line
Alias: n
Usage: next
Proceed to the next or the specified breakpoint
Alias: c
Usage: continue [BREAKPOINT_KEY]
Optional arg BREAKPOINT_KEY is the key of a breakpoint until which continue the build.
Use breakpoints command to list all registered breakpoints.
Execute command in the step.
Alias: e
Usage: exec [OPTIONS] [ARGS...]
If ARGS isn't provided, /bin/sh is used by default.
Flags:
--image: Execute command in the debuger image specified by --image flag of buildg debug. If not specified, the command is executed on the rootfs of the current step. See ./docs/bringing-image.md for details.--mountroot value: Mountpoint to mount the rootfs of the step. ignored if --image isn't specified. (default: /debugroot)--init-state: Execute commands in an initial state of that step (experimental)--tty, -t: Allocate tty (enabled by default)-i: Enable stdin. (FIXME: must be set with tty) (enabled by default)--env value, -e value: Set environment variables--workdir value, -w value: Working directory inside the containerList source lines
Aliases: ls, l
Usage: list [OPTIONS]
Flags:
--all: show all lines-A value: Print the specified number of lines after the current line (default: 3)-B value: Print the specified number of lines before the current line (default: 3)--range value: Print the specified number of lines before and after the current line (default: 3)Show build log
Usage: log [OPTIONS]
Flags:
-n value: Print recent n lines (default: 10)--all, -a: show all lines--more: show buffered and unread linesReload context and restart build
Usage: reload
Exit command
Aliases: quit, q
Usage: exit
Shows a list of commands or help for one command
Alias: h
Usage: help [COMMAND]
--root : Path to the root directory for storing data (e.g. "/var/lib/buildg").--oci-worker-snapshotter value: Worker snapshotter: "auto", "overlayfs", "native" (default: "auto")--oci-worker-net value: Worker network type: "auto", "cni", "host" (default: "auto")--oci-cni-config-path value: Path to CNI config file (default: "/etc/buildkit/cni.json")--oci-cni-binary-path value: Path to CNI plugin binary dir (default: "/opt/cni/bin")--rootlesskit-args: Change arguments for rootlesskit in JSON format [BUILDG_ROOTLESSKIT_ARGS]./docs/cache-from.md: Inspecting remotely cached build using --cache-from flag../docs/bringing-image.md: Bringging your own image for debugging instructions using --image flag.No open issues yet, or sync has not completed.