[⬇️ 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) quit

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:

• 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.

• buildctl by 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
  • break
  • breakpoints
  • clear
  • clearall
  • next
  • continue
  • exec
  • list
  • log
  • reload
  • exit
  • help
• 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 --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 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 --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 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-from flag.
• ./docs/bringing-image.md: Bringging your own image for debugging instructions using --image flag.