dhi: refresh troubleshoot & debug (#24658)

craig-osterhout · aevesdocker · web-flow · commit fa88f5d2e84b · 2026-04-08T08:44:59.000-07:00
## Description Merged how-to/debug into troubleshoot to reduce left nav sprawl. Kept troubleshoot at top-level to align with other manuals. https://deploy-preview-24658--docsdocker.netlify.app/dhi/troubleshoot/ ## Related issues or tickets  ## Reviews   - [ ] Editorial review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com> Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
diff --git a/content/guides/dhi-backstage.md b/content/guides/dhi-backstage.md
@@ -430,7 +430,7 @@ docker exec -it <container-id> sh
 OCI runtime exec failed: exec failed: unable to start container process: ...
 ```
 
-Use [Docker Debug](/dhi/how-to/debug/) if you need to troubleshoot a running distroless container.
+Use [Docker Debug](/dhi/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container.
 
 > [!NOTE]
 >
@@ -480,4 +480,4 @@ Different scanners detect different issues. Running all three gives you the most
 - [Use the DHI CLI](/dhi/how-to/cli/) — manage DHI images, mirrors, and customizations from the command line.
 - [Migrate to DHI](/dhi/migration/) — for applications that work with standard DHI images without additional packages.
 - [Compare images](/dhi/how-to/explore/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images.
-- [Docker Debug](/dhi/how-to/debug/) — troubleshoot distroless containers that have no shell.
+- [Docker Debug](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell.
diff --git a/content/guides/dhi-openshift.md b/content/guides/dhi-openshift.md
@@ -620,6 +620,6 @@ and use `COPY --chown` to transfer results.
 
 - [Use an image in Kubernetes](/dhi/how-to/k8s/) — general DHI Kubernetes deployment guide.
 - [Customize an image](/dhi/how-to/customize/) — add packages to DHI images using Enterprise customization.
-- [Debug a container](/dhi/how-to/debug/) — troubleshoot distroless containers with Docker Debug (local development).
+- [Debug a container](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development).
 - [Managing SCCs](https://docs.openshift.com/container-platform/4.14/authentication/managing-security-context-constraints.html) — Red Hat’s reference documentation on Security Context Constraints.
 - [Creating images for OpenShift](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html) — Red Hat’s guidelines for building OpenShift-compatible container images.
diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md
@@ -1,6 +1,6 @@
 ---
 title: How-tos
-description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging.
+description: Step-by-step guidance for working with Docker Hardened Images, from discovery to governance.
 weight: 20
 params:
   grid_discover:
@@ -63,17 +63,12 @@ params:
       description: Learn how to use image policies with Docker Scout for Docker Hardened Images.
       icon: policy
       link: /dhi/how-to/policies/
-  grid_troubleshoot:
-    - title: Debug a Docker Hardened Image
-      description: Use Docker Debug to inspect a running container based on a hardened image without modifying it.
-      icon: terminal
-      link: /dhi/how-to/debug/
 ---
 
 This section provides practical, task-based guidance for working with Docker
 Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or
 integrating them into a production CI/CD pipeline, these topics cover the key
-tasks across the adoption journey, from discovery to debugging.
+tasks across the adoption journey: discover, adopt, verify, and govern.
 
 The topics are organized around the typical lifecycle of working with DHIs, but
 you can use them as needed based on your specific workflow.
@@ -111,11 +106,3 @@ Enforce policies to maintain security and compliance.
 {{< grid
   items="grid_govern"
 >}}
-
-## Troubleshoot
-
-Debug containers based on DHIs without modifying the image.
-
-{{< grid
-  items="grid_troubleshoot"
->}}
diff --git a/content/manuals/dhi/how-to/debug.md b/content/manuals/dhi/how-to/debug.md
diff --git a/content/manuals/dhi/troubleshoot.md b/content/manuals/dhi/troubleshoot.md
@@ -3,27 +3,132 @@ title: Troubleshoot
 description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access.
 weight: 40
 tags: [Troubleshooting]
-keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager
+keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager, debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container
+aliases:
+- /dhi/how-to/debug/
 ---
 
-The following are common issues you may encounter while migrating to or using
-Docker Hardened Images (DHIs), along with recommended solutions.
+This page covers debugging techniques and common issues you may encounter while
+migrating to or using Docker Hardened Images (DHIs).
 
 ## General debugging
 
-Docker Hardened Images are optimized for security and runtime performance. As
-such, they typically don't include a shell or standard debugging tools. The
-recommended way to troubleshoot containers built on DHIs is by using [Docker
-Debug](./how-to/debug.md).
+Docker Hardened Images prioritize minimalism and security, which means
+they intentionally leave out many common debugging tools (like shells or package
+managers). This makes direct troubleshooting difficult without introducing risk.
+To address this, you can use [Docker
+Debug](/reference/cli/docker/debug/), a secure workflow that
+temporarily attaches an ephemeral debug container to a running service or image
+without modifying the original image.
 
-Docker Debug allows you to:
+This section shows how to debug Docker Hardened Images locally during development.
+With Docker Debug, you can also debug containers remotely using the `--host`
+option.
 
-- Attach a temporary debug container to your existing container.
-- Use a shell and familiar tools such as `curl`, `ps`, `netstat`, and `strace`.
-- Install additional tools as needed in a writable, ephemeral layer that
-  disappears after the session.
+### Use Docker Debug
 
-## Permissions
+#### Step 1: Run a container from a Hardened Image
+
+Start with a DHI-based container that simulates an issue:
+
+```console
+$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"
+```
+
+This container doesn't include a shell or tools like `ps`, `top`, or `cat`.
+
+If you try:
+
+```console
+$ docker exec -it myapp sh
+```
+
+You'll see:
+
+```console
+exec: "sh": executable file not found in $PATH
+```
+
+#### Step 2: Use Docker Debug to inspect the container
+
+Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance.
+
+```console
+$ docker debug myapp
+```
+
+From here, you can inspect running processes, network status, or mounted files.
+
+For example, to check running processes:
+
+```console
+$ ps aux
+```
+
+Type `exit` to leave the container when done.
+
+### Alternative debugging approaches
+
+In addition to using Docker Debug, you can also use the following approaches for
+debugging DHI containers.
+
+#### Use the -dev variant
+
+Docker Hardened Images offer a `-dev` variant that includes a shell
+and a package manager to install debugging tools. Simply replace the image tag
+with `-dev`:
+
+```console
+$ docker run -it --rm dhi.io/python:3.13-dev sh
+```
+
+Type `exit` to leave the container when done. Note that using the `-dev` variant
+increases the attack surface and it is not recommended as a runtime for
+production environments.
+
+#### Mount debugging tools with image mounts
+
+You can use the image mount feature to mount debugging tools into your container
+without modifying the base image.
+
+##### Step 1: Run a container from a hardened image
+
+Start with a DHI-based container that simulates an issue:
+
+```console
+$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"
+```
+
+##### Step 2: Mount debugging tools into the container
+
+Run a new container that mounts a tool-rich image (like `busybox`) into
+the running container's namespace:
+
+```console
+$ docker run --rm -it --pid container:myapp \
+  --mount type=image,source=busybox,destination=/dbg,ro \
+  dhi.io/python:3.13 /dbg/bin/sh
+```
+
+This mounts the BusyBox image at `/dbg`, giving you access to its tools while
+keeping your original container image unchanged. Since the hardened Python image
+doesn't include standard utilities, you need to use the full path to the mounted
+tools:
+
+```console
+$ /dbg/bin/ls /
+$ /dbg/bin/ps aux
+$ /dbg/bin/cat /etc/os-release
+```
+
+Type `exit` to leave the container when done.
+
+## Common issues
+
+The following are specific issues you may encounter when working with Docker
+Hardened Images, along with recommended solutions.
+
+### Permissions
 
 DHIs run as a nonroot user by default for enhanced security. This can result in
 permission issues when accessing files or directories. Ensure your application
@@ -34,7 +139,7 @@ To find out which user a DHI runs as, check the repository page for the image on
 Docker Hub. See [View image variant
 details](./how-to/explore.md#image-variant-details) for more information.
 
-## Privileged ports
+### Privileged ports
 
 Nonroot containers cannot bind to ports below 1024 by default. This is enforced
 by both the container runtime and the kernel (especially in Kubernetes and
@@ -45,7 +150,7 @@ port (1025 or higher). For example `docker run -p 80:8080 my-image` maps
 port 8080 in the container to port 80 on the host, allowing you to access it
 without needing root privileges.
 
-## No shell
+### No shell
 
 Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or
 tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev`
@@ -56,10 +161,10 @@ To find out which shell, if any, a DHI has, check the repository page for the
 image on Docker Hub. See [View image variant
 details](./how-to/explore.md#image-variant-details) for more information.
 
-Also, use [Docker Debug](./how-to/debug.md) when you need shell
-access to a running container.
+Also, use Docker Debug when you need shell access to a running container. For
+more details, see [General debugging](#general-debugging).
 
-## Entry point differences
+### Entry point differences
 
 DHIs may define different entry points compared to Docker Official Images (DOIs)
 or other community images.
@@ -68,7 +173,7 @@ To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the
 image on Docker Hub. See [View image variant
 details](./how-to/explore.md#image-variant-details) for more information.
 
-## No package manager
+### No package manager
 
 Runtime Docker Hardened Images are stripped down for security and minimal attack
 surface. As a result, they don't include a package manager such as `apk` or
