From c5950f3ded156aa6477735db0ea77521566a9e87 Mon Sep 17 00:00:00 2001 From: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> Date: Mon, 8 Apr 2024 08:12:37 -0700 Subject: [PATCH] desktop: add debug gui (#19583) * add debug gui Signed-off-by: Craig Osterhout * feedback1 Signed-off-by: Craig Osterhout * Update content/desktop/use-desktop/container.md Co-authored-by: Stephanie Aurelio <133041642+stephaurelio@users.noreply.github.com> --------- Signed-off-by: Craig Osterhout Co-authored-by: Stephanie Aurelio <133041642+stephaurelio@users.noreply.github.com> --- content/desktop/settings/linux.md | 2 + content/desktop/settings/mac.md | 2 + content/desktop/settings/windows.md | 2 + content/desktop/use-desktop/container.md | 98 +++++++++++++++++++----- data/redirects.yml | 3 + 5 files changed, 86 insertions(+), 21 deletions(-) diff --git a/content/desktop/settings/linux.md b/content/desktop/settings/linux.md index 13724bc531..d1143cfe46 100644 --- a/content/desktop/settings/linux.md +++ b/content/desktop/settings/linux.md @@ -29,6 +29,8 @@ On the **General** tab, you can configure when to start Docker and specify other - **Choose container terminal**. Determines which terminal is launched when opening the terminal from a container. If you choose the integrated terminal, you can run commands in a running container straight from the Docker Dashboard. For more information, see [Explore containers](../use-desktop/container.md). +- **Enable Docker Debug by default**. Check this option to use Docker Debug by default when accessing the integrated terminal. For more information, see [Explore containers](../use-desktop/container.md#integrated-terminal). + - **Use containerd for pulling and storing images**. Turns on the containerd image store. This brings new features like faster container startup performance by lazy-pulling images, diff --git a/content/desktop/settings/mac.md b/content/desktop/settings/mac.md index 73a6d2b037..f04dc81e84 100644 --- a/content/desktop/settings/mac.md +++ b/content/desktop/settings/mac.md @@ -34,6 +34,8 @@ On the **General** tab, you can configure when to start Docker and specify other - **Choose container terminal**. Determines which terminal is launched when opening the terminal from a container. If you choose the integrated terminal, you can run commands in a running container straight from the Docker Dashboard. For more information, see [Explore containers](../use-desktop/container.md). +- **Enable Docker Debug by default**. Check this option to use Docker Debug by default when accessing the integrated terminal. For more information, see [Explore containers](../use-desktop/container.md#integrated-terminal). + - **Include VM in Time Machine backups**. Select to back up the Docker Desktop virtual machine. This option is turned off by default. diff --git a/content/desktop/settings/windows.md b/content/desktop/settings/windows.md index a6f9cc10a7..e5d54e20f4 100644 --- a/content/desktop/settings/windows.md +++ b/content/desktop/settings/windows.md @@ -29,6 +29,8 @@ On the **General** tab, you can configure when to start Docker and specify other - **Choose container terminal**. Determines which terminal is launched when opening the terminal from a container. If you choose the integrated terminal, you can run commands in a running container straight from the Docker Dashboard. For more information, see [Explore containers](../use-desktop/container.md). +- **Enable Docker Debug by default**. Check this option to use Docker Debug by default when accessing the integrated terminal. For more information, see [Explore containers](../use-desktop/container.md#integrated-terminal). + - **Expose daemon on tcp://localhost:2375 without TLS**. Check this option to enable legacy clients to connect to the Docker daemon. You must use this option with caution as exposing the daemon without TLS can result in remote code diff --git a/content/desktop/use-desktop/container.md b/content/desktop/use-desktop/container.md index d1f29c57d0..752a5b08ce 100644 --- a/content/desktop/use-desktop/container.md +++ b/content/desktop/use-desktop/container.md @@ -29,17 +29,23 @@ When you [inspect a container](#inspect-a-container), the **Stats** tab displays You can obtain detailed information about the container when you select it. -From here, you can use the quick action buttons to perform various actions such as pause, resume, start or stop, or explore the **Logs**, **Inspect**, **Bind mounts**, **Terminal**, **Files**, and **Stats** tabs. +From here, you can use the quick action buttons to perform various actions such as pause, resume, start or stop, or explore the **Logs**, **Inspect**, **Bind mounts**, **Exec**, **Files**, and **Stats** tabs. ### Logs -- Select **Logs** to see logs from the container. You can also: - - Use `Cmd + f`/`Ctrl + f` to open the search bar and find specific entries. Search matches are highlighted in yellow. - - Press `Enter` or `Shift + Enter` to jump to the next or previous search match respectively. - - Use the **Copy** icon in the top right-hand corner to copy all the logs to your clipboard. - - Automatically copy any logs content by highlighting a few lines or a section of the logs. - - Use the **Clear terminal** icon in the top right-hand corner to clear the logs terminal. - - Select and view external links that may be in your logs. +Select **Logs** to see logs from the container. You can also: + +- Use `Cmd + f`/`Ctrl + f` to open the search bar and find specific entries. + Search matches are highlighted in yellow. +- Press `Enter` or `Shift + Enter` to jump to the next or previous search match + respectively. +- Use the **Copy** icon in the top right-hand corner to copy all the logs to + your clipboard. +- Automatically copy any logs content by highlighting a few lines or a section + of the logs. +- Use the **Clear terminal** icon in the top right-hand corner to clear the + logs terminal. +- Select and view external links that may be in your logs. ### Inspect @@ -47,28 +53,78 @@ Select **Inspect** to view low-level information about the container. It display ### Integrated terminal -From the **Exec** tab, lets you use the integrated terminal, on a running container, directly within Docker Desktop. You are able to quickly run commands within your container so you can understand its current state or debug when something goes wrong. +From the **Exec** tab, you can use the integrated terminal, on a running +container, directly within Docker Desktop. You are able to quickly run commands +within your container so you can understand its current state or debug when +something goes wrong. -Using the integrated terminal is the same as running `docker exec -it /bin/sh`, or `docker exec -it cmd.exe` if you are using Windows containers, in your external terminal. It also: +Using the integrated terminal is the same as running one of the following commands: -- Automatically detects the default user for a running container from the image's Dockerfile. If no user is specified it defaults to `root`. -- Persists your session if you navigate to another part of the Docker Dashboard and then return. +- `docker exec -it /bin/sh` +- `docker exec -it cmd.exe` when accessing Windows containers +- `docker debug ` when using debug mode + +The integrated terminal: + +- Persists your session and **Debug mode** setting if you navigate to another + part of the Docker Dashboard and then return. - Supports copy, paste, search, and clearing your session. +- When not using debug mode, it automatically detects the default user for a + running container from the image's Dockerfile. If no user is specified, or + you're using debug mode, it defaults to `root`. + +#### Open the integrated terminal To open the integrated terminal, either: -- Hover over your running container and select the **Show container actions** menu. From the drop-down menu, select **Open in terminal**. -- Select the container and then select the **Exec** tab. -To use your external terminal, navigate to the **General** tab in **Settings** and select the **System default** option under **Choose your terminal**. +- Hover over your running container and select the **Show container actions** + menu. From the drop-down menu, select **Open in terminal**. +- Or, select the container and then select the **Exec** tab. + +To use your external terminal, navigate to the **General** tab in **Settings** +and select the **System default** option under **Choose your terminal**. + +#### Open the integrated terminal in debug mode + +> **Beta** +> +> The debug mode feature is in [Beta](../../release-lifecycle.md/#beta). Docker +> recommends that you don't use this feature in production environments. +{ .experimental } + +Debug mode requires a [Pro, Team, or Business subcription](/subscription/details/). Debug mode has several advantages, such as: + +- A customizable toolbox. The toolbox comes with many standard Linux tools + pre-installed, such as `vim`, `nano`, `htop`, and `curl`. For more details, see the [`docker debug` CLI reference](/reference/cli/docker/debug/). +- The ability to access containers that don't have a shell, for example, slim or + distroless containers. + +To open the integrated terminal in debug mode: + +1. Sign in to Docker Desktop with an account that has a Pro, Team, or Business + subscription. +2. After you're signed in, either: + + - Hover over your running container and select the **Show container actions** + menu. From the drop-down menu, select **Use Docker Debug**. + - Or, select the container and then select the **Debug** tab. If the + **Debug** tab isn't visible, select the **Exec** tab and then enable the + **Debug mode** setting. + +To use debug mode by default when accessing the integrated terminal, navigate to +the **General** tab in **Settings** and select the **Enable Docker Debug by +default** option. ### Files -- Select **Files** to explore the filesystem of running or stopped containers. You can also: - - See which files have been recently added, modified, or deleted - - Edit a file straight from the built-in editor - - Drag and drop files and folders between the host and the container - - Delete unnecessary files when you right-click on a file - - Download file and folders from the container straight to the host +Select **Files** to explore the filesystem of running or stopped containers. You +can also: + +- See which files have been recently added, modified, or deleted +- Edit a file straight from the built-in editor +- Drag and drop files and folders between the host and the container +- Delete unnecessary files when you right-click on a file +- Download files and folders from the container straight to the host ## Additional resources - [What is a container](../../guides/walkthroughs/what-is-a-container.md) diff --git a/data/redirects.yml b/data/redirects.yml index c4d6eaa54d..b43235c125 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -694,5 +694,8 @@ "/get-started/04_sharing_app": - /go/get-started-sharing/ +## Docker Debug "/reference/cli/docker/debug/": - /go/debug-cli/ +"/desktop/use-desktop/container/#integrated-terminal": + - /go/debug-gui/