[⬇️ Download] [📖 Command reference]

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 (needs 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

To use your own image for debugging steps:

buildg debug --image=debugging-tools /path/to/build/context

For the detailed command refenrece, refer to Command reference in the following

Debug the following Dockerfile:

FROM busybox AS build1
RUN echo hello > /hello

FROM busybox AS build2
RUN echo hi > /hi

FROM scratch
COPY --from=build1 /hello /
COPY --from=build2 /hi /

Store this Dockerfile to somewhere (e.g. /tmp/ctx/Dockerfile) then run buildg debug. buildg.sh can be used for rootless execution (discussed later).

$ buildg.sh debug --image=ubuntu:22.04 /tmp/ctx
WARN[2022-05-17T09:01:16Z] using host network as the default            
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 195B done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 2B done
#2 DONE 0.1s

#3 [internal] load metadata for docker.io/library/busybox:latest
INFO[2022-05-17T09:01:19Z] debug session started. type "help" for command reference. 
Filename: "Dockerfile"
 =>   1| FROM busybox AS build1
      2| RUN echo hello > /hello
      3| 
 =>   4| FROM busybox AS build2
      5| RUN echo hi > /hi
      6| 
      7| FROM scratch
(buildg) break 5
(buildg) breakpoints
[0]: line: Dockerfile:5
[on-fail]: breaks on fail
(buildg) continue
#3 DONE 3.2s

#4 [build2 1/2] FROM docker.io/library/busybox@sha256:d2b53584f580310186df7a2055ce3ff83cc0df6caacf1e3489bff8cf5d0af5d8
#4 resolve docker.io/library/busybox@sha256:d2b53584f580310186df7a2055ce3ff83cc0df6caacf1e3489bff8cf5d0af5d8 0.0s done
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 0B / 772.81kB 0.2s
#4 sha256:50e8d59317eb665383b2ef4d9434aeaa394dcd6f54b96bb7810fdde583e9c2d1 772.81kB / 772.81kB 0.9s done
Breakpoint[0]: reached line: Dockerfile:5
Filename: "Dockerfile"
      2| RUN echo hello > /hello
      3| 
      4| FROM busybox AS build2
*=>   5| RUN echo hi > /hi
      6| 
      7| FROM scratch
      8| COPY --from=build1 /hello /
(buildg) exec --image sh
# cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy
# ls /debugroot/
bin  dev  etc  hi  home  proc  root  tmp  usr  var
# cat /debugroot/hi
hi
# 
(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.

• Requirements
  • runc
  • [OPTIONAL] RootlessKit and slirp4netns for rootless execution

Available from https://github.com/ktock/buildg/releases

Install and use buildg.sh. RootlessKit and slirp4netns are needed.

$ buildg.sh debug /path/to/context

The doc in BuildKit project for troubleshooting: 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

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
  • 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.
• --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 (experimental).

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] [ARGS...]

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 breakpoint

Alias: c

Usage: continue

Execute command in the step. Only supported on RUN instructions as of now.

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

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")
• --rootless: Enable rootless configuration

• ./docs/cache-from.md: Inspecting remotely cached build using --cache-from flag.