Troubleshoot
The following are common issues you may encounter while migrating to or using Docker Hardened Images (DHIs), along with recommended solutions.
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.
Docker Debug allows you to:
- Attach a temporary debug container to your existing container.
- Use a shell and familiar tools such as
curl
,ps
,netstat
, andstrace
. - Install additional tools as needed in a writable, ephemeral layer that disappears after the session.
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 files and runtime directories are owned by the expected UID/GID or have appropriate permissions.
To find out which user a DHI runs as, check the repository page for the image on Docker Hub. See View image variant details for more information.
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 Docker Engine < 20.10).
Inside the container, configure your application to listen on an unprivileged
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
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
variant of the image in an earlier build stage and copy the final artifact into
the runtime image.
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 for more information.
Also, use Docker Debug when you need shell access to a running container.
Entry point differences
DHIs may define different entry points compared to Docker Official Images (DOIs) or other community images.
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 for more information.
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
apt
. This means you can't install additional software directly in the runtime
image.
If your build or application setup requires installing packages (for example, to
compile code, install runtime dependencies, or add diagnostic tools), use a dev
variant of the image in a build stage. Then, copy only the necessary artifacts
into the final runtime image.