github.com/pdmccormick/importable-docker-buildx@v0.0.0-20240426161518-e47091289030/docs/debugging.md (about) 1 # Debug monitor 2 3 To assist with creating and debugging complex builds, Buildx provides a 4 debugger to help you step through the build process and easily inspect the 5 state of the build environment at any point. 6 7 > **Note** 8 > 9 > The debug monitor is a new experimental feature in recent versions of Buildx. 10 > There are rough edges, known bugs, and missing features. Please try it out 11 > and let us know what you think! 12 13 ## Starting the debugger 14 15 To start the debugger, first, ensure that `BUILDX_EXPERIMENTAL=1` is set in 16 your environment. 17 18 ```console 19 $ export BUILDX_EXPERIMENTAL=1 20 ``` 21 22 To start a debug session for a build, you can use the `buildx debug` command with `--invoke` flag to specify a command to launch in the resulting image. 23 `buildx debug` command provides `buildx debug build` subcommand that provides the same features as the normal `buildx build` command but allows launching the debugger session after the build. 24 25 Arguments available after `buildx debug build` are the same as the normal `buildx build`. 26 27 ```console 28 $ docker buildx debug --invoke /bin/sh build . 29 [+] Building 4.2s (19/19) FINISHED 30 => [internal] connecting to local controller 0.0s 31 => [internal] load build definition from Dockerfile 0.0s 32 => => transferring dockerfile: 32B 0.0s 33 => [internal] load .dockerignore 0.0s 34 => => transferring context: 34B 0.0s 35 ... 36 Launching interactive container. Press Ctrl-a-c to switch to monitor console 37 Interactive container was restarted with process "dzz7pjb4pk1mj29xqrx0ac3oj". Press Ctrl-a-c to switch to the new container 38 Switched IO 39 / # 40 ``` 41 42 This launches a `/bin/sh` process in the final stage of the image, and allows 43 you to explore the contents of the image, without needing to export or load the 44 image outside of the builder. 45 46 For example, you can use `ls` to see the contents of the image: 47 48 ```console 49 / # ls 50 bin etc lib mnt proc run srv tmp var 51 dev home media opt root sbin sys usr work 52 ``` 53 54 Optional long form allows you specifying detailed configurations of the process. 55 It must be CSV-styled comma-separated key-value pairs. 56 Supported keys are `args` (can be JSON array format), `entrypoint` (can be JSON array format), `env` (can be JSON array format), `user`, `cwd` and `tty` (bool). 57 58 Example: 59 60 ``` 61 $ docker buildx debug --invoke 'entrypoint=["sh"],"args=[""-c"", ""env | grep -e FOO -e AAA""]","env=[""FOO=bar"", ""AAA=bbb""]"' build . 62 ``` 63 64 #### `on` flag 65 66 If you want to start a debug session when a build fails, you can use 67 `--on=error` to start a debug session when the build fails. 68 69 ```console 70 $ docker buildx debug --on=error build . 71 [+] Building 4.2s (19/19) FINISHED 72 => [internal] connecting to local controller 0.0s 73 => [internal] load build definition from Dockerfile 0.0s 74 => => transferring dockerfile: 32B 0.0s 75 => [internal] load .dockerignore 0.0s 76 => => transferring context: 34B 0.0s 77 ... 78 => ERROR [shell 10/10] RUN bad-command 79 ------ 80 > [shell 10/10] RUN bad-command: 81 #0 0.049 /bin/sh: bad-command: not found 82 ------ 83 Launching interactive container. Press Ctrl-a-c to switch to monitor console 84 Interactive container was restarted with process "edmzor60nrag7rh1mbi4o9lm8". Press Ctrl-a-c to switch to the new container 85 / # 86 ``` 87 88 This allows you to explore the state of the image when the build failed. 89 90 #### Launch the debug session directly with `buildx debug` subcommand 91 92 If you want to drop into a debug session without first starting the build, you 93 can use `buildx debug` command to start a debug session. 94 95 ``` 96 $ docker buildx debug 97 [+] Building 4.2s (19/19) FINISHED 98 => [internal] connecting to local controller 0.0s 99 (buildx) 100 ``` 101 102 You can then use the commands available in [monitor mode](#monitor-mode) to 103 start and observe the build. 104 105 ## Monitor mode 106 107 By default, when debugging, you'll be dropped into a shell in the final stage. 108 109 When you're in a debug shell, you can use the `Ctrl-a-c` key combination (press 110 `Ctrl`+`a` together, lift, then press `c`) to toggle between the debug shell 111 and the monitor mode. In monitor mode, you can run commands that control the 112 debug environment. 113 114 ```console 115 (buildx) help 116 Available commands are: 117 attach attach to a buildx server or a process in the container 118 disconnect disconnect a client from a buildx server. Specific session ID can be specified an arg 119 exec execute a process in the interactive container 120 exit exits monitor 121 help shows this message. Optionally pass a command name as an argument to print the detailed usage. 122 kill kill buildx server 123 list list buildx sessions 124 ps list processes invoked by "exec". Use "attach" to attach IO to that process 125 reload reloads the context and build it 126 rollback re-runs the interactive container with the step's rootfs contents 127 ``` 128 129 ## Build controllers 130 131 Debugging is performed using a buildx "controller", which provides a high-level 132 abstraction to perform builds. By default, the local controller is used for a 133 more stable experience which runs all builds in-process. However, you can also 134 use the remote controller to detach the build process from the CLI. 135 136 To detach the build process from the CLI, you can use the `--detach=true` flag with 137 the build command. 138 139 ```console 140 $ docker buildx debug --invoke /bin/sh build --detach=true . 141 ``` 142 143 If you start a debugging session using the `--invoke` flag with a detached 144 build, then you can attach to it using the `buildx debug` command to 145 immediately enter the monitor mode. 146 147 ```console 148 $ docker buildx debug 149 [+] Building 0.0s (1/1) FINISHED 150 => [internal] connecting to remote controller 151 (buildx) list 152 ID CURRENT_SESSION 153 xfe1162ovd9def8yapb4ys66t false 154 (buildx) attach xfe1162ovd9def8yapb4ys66t 155 Attached to process "". Press Ctrl-a-c to switch to the new container 156 (buildx) ps 157 PID CURRENT_SESSION COMMAND 158 3ug8iqaufiwwnukimhqqt06jz false [sh] 159 (buildx) attach 3ug8iqaufiwwnukimhqqt06jz 160 Attached to process "3ug8iqaufiwwnukimhqqt06jz". Press Ctrl-a-c to switch to the new container 161 (buildx) Switched IO 162 / # ls 163 bin etc lib mnt proc run srv tmp var 164 dev home media opt root sbin sys usr work 165 / # 166 ```