Customize a Docker Hardened Image

Table of contents

You can customize a Docker Hardened Image (DHI) to suit your specific needs using the Docker Hub UI. This allows you to select a base image, add packages, add artifacts, and configure settings. In addition, the build pipeline ensures that your customized image is built securely and includes attestations.

To add a customized Docker Hardened Image to your organization, an organization owner must first mirror the DHI repository to your organization. Once the repository is mirrored, any user with access to the mirrored DHI repository can create a customized image.

Customize a Docker Hardened Image

To customize a Docker Hardened Image, follow these steps:

Sign in to Docker Hub.
Select My Hub.
In the namespace drop-down, select your organization that has a mirrored DHI repository.
Select the mirrored DHI repository.
Select the Customizations tab.
Select Create customization.
At this point, the on-screen instructions will guide you through the customization process. You can continue with the following steps for more details.
Select the image version you want to customize.
Add packages.
1. In the Packages drop-down, select the packages you want to add to the image.
  The packages available in the drop-down are OS system packages for the selected image variant. For example, if you are customizing the Alpine variant of the Python DHI, the list will include all Alpine system packages.
2. In the OCI artifacts drop-down, first, select the repository that contains the OCI artifact image. Then, select the tag you want to use from that repository. Finally, specify the specific paths you want to include from the OCI artifact image.
  The OCI artifacts are images that you have previously built and pushed to a repository in the same namespace as the mirrored DHI. For example, you can add a custom root CA certificate or a another image that contains a tool you need, like adding Python to a Node.js image. For more details on how to create an OCI artifact image, see Create an OCI artifact image.
  When combining images that contain directories and files with the same path, images later in the list will overwrite files from earlier images. To manage this, you must select paths to include and optionally exclude from each OCI artifact image. This allows you to control which files are included in the final customized image.
  By default, no files are included from the OCI artifact image. You must explicitly include the paths you want. After including a path, you can then explicitly exclude files or directories underneath it.
  Note
  When files necessary for runtime are overwritten by OCI artifacts, the image build still succeeds, but you may have issues when running the image.
Select Next: Configure and then configure the following options.
1. Specify a suffix that is appended to the customized image's tag. For example, if you specify custom when customizing the dhi-python:3.13 image, the customized image will be tagged as dhi-python:3.13_custom.
2. Select the platforms you want to build the image for.
3. Add ENTRYPOINT and CMD arguments to the image. These arguments are appended to the base image's entrypoint and command.
4. Specify the users to add to the image.
5. Specify the user groups to add to the image.
6. Select which user to run the images as.
7. Specify the environment variables and their values that the image will contain.
8. Add annotations to the image.
9. Add labels to the image.
Select Create Customization.
A summary of the customization appears. It may take some time for the image to build. Once built, it will appear in the Tags tab of the repository, and your team members can pull it like any other image.

Edit or delete a Docker Hardened Image customization

To edit or delete a Docker Hardened Image customization, follow these steps:

Sign in to Docker Hub.
Select My Hub.
In the namespace drop-down, select your organization that has a mirrored DHI.
Select the mirrored DHI repository.
Select the Customizations tab.
Select Edit to edit the customization, or select the trashcan icon to delete the customization.
Follow the on-screen instructions to complete the edit or deletion.

Create an OCI artifact image

An OCI artifact image is a Docker image that contains files or directories that you want to include in your customized Docker Hardened Image (DHI). This can include additional tools, libraries, or configuration files.

When creating an image to use as an OCI artifact, it should ideally be as minimal as possible and contain only the necessary files.

For example, to distribute a custom root CA certificate as part of a trusted CA bundle, you can use a multi-stage build. This approach registers your certificate with the system and outputs an updated CA bundle, which can be extracted into a minimal final image:

# syntax=docker/dockerfile:1

FROM <your-namespace>/dhi-bash:5-dev AS certs

ENV DEBIAN_FRONTEND=noninteractive

RUN mkdir -p /usr/local/share/ca-certificates/my-rootca
COPY certs/rootCA.crt /usr/local/share/ca-certificates/my-rootca

RUN update-ca-certificates

FROM scratch
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

You can follow this pattern to create other OCI artifacts, such as images containing tools or libraries that you want to include in your customized DHI. Install the necessary tools or libraries in the first stage, and then copy the relevant files to the final stage that uses FROM scratch. This ensures that your OCI artifact is minimal and contains only the necessary files.

Build and push the OCI artifact image to a repository in your organization's namespace and it automatically appears in the customization workflow when you select the OCI artifacts to add to your customized Docker Hardened Image.