Buildx Debugging for Dockerfiles

To debug Dockerfiles, you can use the DAP implementation provided by Buildx.

Requirements

You will need Buildx v0.28.0. You can get Buildx by installing Docker Desktop or by installing Buildx manually.

Run docker buildx version to check your Buildx version.
Run BUILDX_EXPERIMENTAL=1 docker buildx dap to check that the dap subcommand is available in your Buildx installation.

Setup

Create a Debug Adapter Protocol launch configuration.

Click on the 'Create a new server' hyperlink.

Click 'Choose template...' and select the 'Docker: Dockerfile Build Debugging' template.

In 'Environment variables:', enter in BUILDX_EXPERIMENTAL=1.

Click the 'OK' button to save the server configuration.
Now go to the 'Configuration' tab and find select a Dockerfile in the 'File:' field.

Click the 'OK' button to save the launch configuration.
Open your Dockerfile and place a breakpoint.
Launch your configuration in debug mode to pause the Dockerfile build!

Configuration

If you would like to make further configurations to how the build is launched, you can refer to this document to modify the DAP JSON parameters that are passed.

Features

View the environment of the image being built

While your build is in a suspended state, you can review variables, the working directory, and the files and folders of the image.

Open a shell inside the image

Evaluate the exec expression and Buildx will open a terminal for you to type commands into the image directly.

Please note however that any changes you make will be wiped when you advance the debugger.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!