Interactive Debugging of Dockerfile on VS Code, Emacs and Neovim

Kohei Tokunaga
nttlabs
Published in
4 min readJul 13, 2022

Debugging Dockerfile is hard and takes a long time sometimes. To solve this issue, we’re working on buildg, an interactive debugger for Dockerfile with support for VS Code, Emacs and Neovim, etc.

Interactive debugging of Dockerfile on IDE

What’s buildg?

buildg is an interactive debugger for Dockerfile.

This supports breakpoints, stepping through line by line and launching a shell on a Dockerfile instruction with your own debugging tools. See the previous post for more information and examples on the terminal.

Debugging Dockerifles on IDEs via Debug Adapter Protocol (DAP)

buildg v0.3.0 added initial support for GUI-based debugging of Dockerfiles on IDEs like VS Code, Emacs and Neovim, etc.

This feature is implemented by leveraging Debug Adapter Protocol (DAP). DAP is the standard protocol between an IDE and a debugger. IDEs including VS Code, Emacs and Neovim provide rich GUI for debugging programs and use DAP to control the corresponding debugger.

Debug Adapter Protocol

buildg implements DAP and provides debugging functionality for Dockerfile. So you can use your favourite IDE to debug Dockerfiles.

Debug Adapter Protocol on buildg

Getting Started

buildg v0.3.0 or newer needs to be installed. Release binaries of buildg are available on GitHub: https://github.com/ktock/buildg/releases . Please refer to the repository for installation details.

On VS Code, install an extension vscode-buildg to allow VS Code to use buildg for debugging Dockerfiles.

The released VSIX file of vscode-buildg is available on GitHub repo: https://github.com/ktock/vscode-buildg/releases . You can install the downloaded VSIX file to VS Code as the following.

code --install-extension buildg-${VERSION}.vsix

NOTE: This extension isn’t available on Visual Stdio Marketplace as of now. We will distribute it there in the future.

You can also use Emacs and Neovim to debug Dockerfiles. The documentation and configuration examples are available on buildg repo.

Example of debugging Dockerfile on IDE

This section shows an example of interactive debugging of Dockerfile on IDE. We use VS Code here. Other DAP-aware IDEs also provide the similar UI/UX.

Let’s consider the following Dockerfile that creates a file at the image’s root directory.

ARG MESSAGE="Hello, World!"FROM ubuntu:22.04
RUN apt-get update && apt-get install -y figlet
ARG MESSAGE
RUN figlet $MESSAGE > /hi

To enable debugging of this Dockerfiles on VS Code, you first needs to create a launch configuration file (.vscode/launch.json) in the workspace. Please refer to the document for available properties.

{
"version": "0.2.0",
"configurations": [
{
"type": "dockerfile",
"request": "launch",
"name": "Debug Dockerfile",
"program": "${workspaceFolder}/Dockerfile",
"stopOnEntry": true
}
]
}

Pushing F5 key starts the debugger. The build progress is shown in DEBUG CONSOLE panel. Then the build will stop at line 3 (FROM ubuntu:22.04) which is highlighted.

Build stops at line 3

You can set a breakpoint using F9 on the target line. Now we have a breakpoint at line 6 (RUN figlet $MESSAGE > /hi) marked with a red filled circle.

Set breakpoint at line 6

“Continue” button on the toolbar or F5 resumes the build. Then it will pause at the breakpoint line 6 (RUN figlet $MESSAGE > /hi). You can deeply inspect this RUN instruction by launching a shell using exec command in the debug console.

Build stops at line 6

exec automatically launches a shell in the Terminal panel. Here we can inspect the file hi created by this RUN instruction.

Inspect a file created by the RUN instruction using shell

This section briefly introduced interactive debugging of Dockerfile on VS Code. For further information and usages for other IDEs, refer to the documentation.

NTT is hiring!

We NTT is looking for engineers who work in Open Source communities like containerd, Docker/Moby and Kubernetes. Visit https://www.rd.ntt/e/sic/recruit/ to see how to join us.

--

--