[⬇️ Download] [📖 Command reference] [🖥 Use on IDEs]
buildg is a tool to interactively debug Dockerfile based on BuildKit.
- Source-level inspection
- Breakpoints and step execution
- Interactive shell on a step with your own debugigng tools
- Based on BuildKit (with unmerged patches)
- Supports rootless
early stage software This is implemented based on BuildKit with some unmerged patches. We're planning to upstream them.
buildg debug /path/to/build/context
The 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 debug /tmp/ctx
WARN[2022-09-20T20:11:49+09:00] using host network as the default
#1 [internal] load .dockerignore
#1 transferring context: 2B done
#1 DONE 0.0s
#2 [internal] load build definition from Dockerfile
#2 transferring dockerfile: 170B done
#2 DONE 0.0s
#3 [internal] load metadata for docker.io/library/ubuntu:latest
#3 ...
#4 [auth] library/ubuntu:pull token for registry-1.docker.io
#4 DONE 0.0s
#3 [internal] load metadata for docker.io/library/ubuntu:latest
#3 DONE 2.2s
#5 [dev 1/3] FROM docker.io/library/ubuntu@sha256:20fa2d7bb4de7723f542be5923b06c4d704370f0390e4ae9e1c833c8785644c1
#5 resolve docker.io/library/ubuntu@sha256:20fa2d7bb4de7723f542be5923b06c4d704370f0390e4ae9e1c833c8785644c1
INFO[2022-09-20T20:11:52+09:00] CACHED [dev 1/3] FROM docker.io/library/ubuntu@sha256:20fa2d7bb4de7723f542be5923b06c4d704370f0390e4ae9e1c833c8785644c1
INFO[2022-09-20T20:11:52+09:00] debug session started. type "help" for command reference.
Filename: "Dockerfile"
=> 1| FROM ubuntu AS dev
2| RUN echo hello > /hello
3| RUN echo world > /world
4|
(buildg) break 3
(buildg) continue
#5 resolve docker.io/library/ubuntu@sha256:20fa2d7bb4de7723f542be5923b06c4d704370f0390e4ae9e1c833c8785644c1 0.0s done
#5 DONE 0.0s
INFO[2022-09-20T20:11:54+09:00] CACHED [dev 2/3] RUN echo hello > /hello
INFO[2022-09-20T20:11:54+09:00] detected 127.0.0.53 nameserver, assuming systemd-resolved, so using resolv.conf: /run/systemd/resolve/resolv.conf
#6 [dev 2/3] RUN echo hello > /hello
#6 CACHED
#7 [dev 3/3] RUN echo world > /world
Breakpoint[0]: reached line: Dockerfile:3
Filename: "Dockerfile"
1| FROM ubuntu AS dev
2| RUN echo hello > /hello
*=> 3| RUN echo world > /world
4|
5| FROM scratch
6| COPY --from=dev /hello /
(buildg) exec
# cat /hello /world
hello
world
#
(buildg) quitBuildg 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:
- runc
- [OPTIONAL] RootlessKit and slirp4netns for rootless execution
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.18+ is needed.
$ git clone https://github.com/ktock/buildg
$ cd buildg
$ make
$ sudo make install
nerdctl 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/context
You 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 /ctx
You 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 /ctx
You can also use bake command by Docker Buildx to build the container:
docker buildx bake --set image-local.tags=buildg
Tip: 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. moby/buildkit#2813, moby/buildkit#1472, moby/buildkit#749). Leveraging the generic features added through the work, this project implements a PoC for providing easy UI/UX to debug Dockerfile.
buildctlby BuildKit : has debug commands to inspect buildkitd, LLB, etc. but no interactive debugging for builds.- cntr : allows attaching and debugging containers but no interactive debugging for builds.
- ctr by containerd : allows directly controlling and inspecting containerd resources (e.g. contents, snapshots, etc.) but no interactive debugging for builds.
- buildg debug
- buildg prune
- buildg du
- buildg dap serve
- buildg dap prune
- buildg dap du
- Debug shell commands
- Global flags
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--imageflag forexeccommand in debug shell when use this image. See./docs/bringing-image.mdfor 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 references
Show 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 logs
Prune DAP cache.
See ./examples/dap/README.md for usage of DAP.
Usage: buildg dap prune [OPTIONS]
Flags:
--all: Prune including internal/frontend references
Show 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.
- line number: breaks at the line number in Dockerfile
on-fail: breaks on step that returns an error
Show 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--imageflag ofbuildg debug. If not specified, the command is executed on the rootfs of the current step. See./docs/bringing-image.mdfor details.--mountroot value: Mountpoint to mount the rootfs of the step. ignored if--imageisn'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 container
List 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 lines
Reload 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-fromflag../docs/bringing-image.md: Bringging your own image for debugging instructions using--imageflag.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
