From 4ce80856b39495fd745262ff4b2ec6d31800ded5 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Fri, 19 May 2023 14:51:51 +0100 Subject: [PATCH] docs: add info for on-error and debug-shell values for invoke Signed-off-by: Justin Chadwell --- docs/guides/debugging.md | 41 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md index 87f57a9d..df1b49b8 100644 --- a/docs/guides/debugging.md +++ b/docs/guides/debugging.md @@ -49,6 +49,47 @@ bin etc lib mnt proc run srv tmp var dev home media opt root sbin sys usr work ``` +#### `on-error` + +If you want to start a debug session when a build fails, you can use +`--invoke=on-error` to start a debug session when the build fails. + +```console +$ docker buildx build --invoke on-error . +[+] Building 4.2s (19/19) FINISHED + => [internal] connecting to local controller 0.0s + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 32B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 34B 0.0s + ... + => ERROR [shell 10/10] RUN bad-command +------ + > [shell 10/10] RUN bad-command: +#0 0.049 /bin/sh: bad-command: not found +------ +Launching interactive container. Press Ctrl-a-c to switch to monitor console +Interactive container was restarted with process "edmzor60nrag7rh1mbi4o9lm8". Press Ctrl-a-c to switch to the new container +/ # +``` + +This allows you to explore the state of the image when the build failed. + +#### `debug-shell` + +If you want to drop into a debug session without first starting the build, you +can use `--invoke=debug-shell` to start a debug session. + +``` +$ docker buildx build --invoke debug-shell . +[+] Building 4.2s (19/19) FINISHED + => [internal] connecting to local controller 0.0s +(buildx) +``` + +You can then use the commands available in [monitor mode](#monitor-mode) to +start and observe the build. + ## Monitor mode By default, when debugging, you'll be dropped into a shell in the final stage.