instruction: Explain Use an image
output: Back
  Ask AI
  Start typing to search or try
  Contact support
  Manuals
  Get started
  Guides
  Use a Docker Hardened Image
  Page options
  Copy page as Markdown for LLMs
  View page as plain text
  Ask questions with Docs AI
  Claude
  Open in Claude
  Subscription:
  Docker Hardened Images
  You can use a Docker Hardened Image (DHI) just like any other image on Docker
  Hub. DHIs follow the same familiar usage patterns. Pull them with
  docker pull
  reference them in your Dockerfile, and run containers with
  docker run
  The key difference is that DHIs are security-focused and intentionally minimal
  to reduce the attack surface. This means some variants don't include a shell or
  package manager, and may run as a nonroot user by default.
  Note
  You don't need to change your existing workflows. Whether you're pulling
  images manually, referencing them in your Dockerfiles, or integrating them
  into CI pipelines, DHIs work just like the images you already use.
  After
  mirroring
  a DHI to your organization's namespace, the image
  becomes available for use. To find your mirrored repository, go to the original
  image's page in the Hardened Images catalog and select
  View in repository
  to show a list of mirrored repositories.
  Considerations when adopting DHIs
  Docker Hardened Images are intentionally minimal to improve security. If you're updating existing Dockerfiles or frameworks to use DHIs, keep the following considerations in mind:
  Feature
  Details
  No shell or package manager
  Runtime images donât include a shell or package manager. Use
  -dev
  -sdk
  variants in build stages to run shell commands or install packages, and then copy artifacts to a minimal runtime image.
  Non-root runtime
  Runtime DHIs default to running as a non-root user. Ensure your application doesn't require privileged access and that all needed files are readable and executable by a non-root user.
  Ports
  Applications running as non-root users can't bind to ports below 1024 in older versions of Docker or in some Kubernetes configurations. Use ports above 1024 for compatibility.
  Entry point
  DHIs may not include a default entrypoint or might use a different one than the original image you're familiar with. Check the image configuration and update your
  ENTRYPOINT
  directives accordingly.
  Multi-stage builds
  Always use multi-stage builds for frameworks: a
  -dev
  image for building or installing dependencies, and a minimal runtime image for the final stage.
  TLS certificates
  DHIs include standard TLS certificates. You do not need to manually install CA certs.
  If you're migrating an existing application, see
  Migrate an existing
  application to use Docker Hardened Images
  Use a DHI in a Dockerfile
  To use a DHI as the base image for your container, specify it in the
  FROM
  instruction in your Dockerfile:
  FROM
  <your-namespace>/dhi-<image>:<tag>
  Replace the image name and tag with the variant you want to use. For example,
  use a
  -dev
  tag if you need a shell or package manager during build stages:
  FROM
  <your-namespace>/dhi-python:3.13-dev AS build
  To learn how to explore available variants, see
  Explore images
  Use a multi-stage Dockerfile to separate build and runtime stages, using a
  -dev
  variant in build stages and a minimal runtime image in the final stage.
  Pull a DHI from Docker Hub
  Just like any other image on Docker Hub, you can pull Docker Hardened Images
  (DHIs) using tools such as the Docker CLI, the Docker Hub Registry API, or
  within your CI pipelines.
  The following example shows how to pull a DHI using the CLI:
  docker pull <your-namespace>/dhi-<image>:<tag>
  You must have access to the image in your Docker Hub namespace. For more
  information, see
  Mirror a Docker Hardened Image
  Run a DHI
  After pulling the image, you can run it using
  docker run
  . For example,
  assuming the repository was mirrored to
  dhi-python
  in your organization
  namespace, start a container and run a Python command:
  docker run --rm <your-namespace>/dhi-python:3.13 python -c
  "print('Hello from DHI')"
  Use a DHI in CI/CD pipelines
  Docker Hardened Images work just like any other image in your CI/CD pipelines.
  You can reference them in Dockerfiles, pull them as part of a pipeline step, or
  run containers based on them during builds and tests.
  Unlike typical container images, DHIs also include signed
  attestations
  such as SBOMs and provenance
  metadata. You can incorporate these into your pipeline to support supply chain
  security, policy checks, or audit requirements if your tooling supports it.
  To strengthen your software supply chain, consider adding your own attestations
  when building images from DHIs. This lets you document how the image was
  built, verify its integrity, and enable downstream validation and
  enforcement
  using tools like Docker Scout.
  To learn how to attach attestations during the build process, see
  Docker Build
  Attestations
  Use a static image for compiled executables
  Docker Hardened Images include a
  static
  image repository designed specifically
  for running compiled executables in an extremely minimal and secure runtime.
  Use a
  -dev
  or other builder image in an earlier stage to compile your binary,
  and copy the output into a
  static
  image.
  The following example shows a multi-stage Dockerfile that builds a Go application
  and runs it in a minimal static image:
  #syntax=docker/dockerfile:1
  FROM
  <your-namespace>/dhi-golang:1.22-dev AS build
  WORKDIR
  /app
  COPY
  CGO_ENABLED
  go build -o myapp
  FROM
  <your-namespace>/dhi-static:20230311
  COPY
  --from
  build /app/myapp /myapp
  ENTRYPOINT
  "/myapp"
  This pattern ensures a hardened runtime environment with no unnecessary
  components, reducing the attack surface to a bare minimum.
  Use dev variants for framework-based applications
  If you're building applications with frameworks that require package managers or
  build tools (such as Python, Node.js, or Go), use a
  -dev
  variant during the
  development or build stage. These variants include essential utilities like
  shells, compilers, and package managers to support local iteration and CI
  workflows.
  -dev
  images in your inner development loop or in isolated CI stages to
  maximize productivity. Once you're ready to produce artifacts for production,
  switch to a smaller runtime variant to reduce the attack surface and image size.
  The following example shows how to build a Python app using a
  -dev
  variant and
  run it using the smaller runtime variant:
  #syntax=docker/dockerfile:1
  FROM
  <your-namespace>/dhi-python:3.13-alpine3.21-dev AS builder
  LANG
  C.UTF-8
  PYTHONDONTWRITEBYTECODE
  PYTHONUNBUFFERED
  PATH
  "/app/venv/bin:
  $PATH
  WORKDIR
  /app
  python -m venv /app/venv
  COPY
  requirements.txt .
  pip install --no-cache-dir -r requirements.txt
  FROM
  <your-namespace>/dhi-python:3.13-alpine3.21
  WORKDIR
  /app
  PYTHONUNBUFFERED
  PATH
  "/app/venv/bin:
  $PATH
  COPY
  image.py image.png ./
  COPY
  --from
  builder /app/venv /app/venv
  ENTRYPOINT
  "python"
  "/app/image.py"
  This pattern separates the build environment from the runtime environment,
  helping reduce image size and improve security by removing unnecessary tooling
  from the final image.