Customize a Docker Hardened Image or chart

When you have a DHI Select or DHI Enterprise subscription, you can customize Docker Hardened Images (DHI) and charts to suit your specific needs using the Docker Hub web interface. For images, this lets you select a base image, add packages, add OCI artifacts (such as custom certificates or additional tools), and configure settings. For charts, this lets you customize the image references.

Your customizations stay secure automatically. When the base Docker Hardened Image or chart receives a security patch or your OCI artifacts are updated, Docker automatically rebuilds your customizations in the background. This ensures continuous compliance and protection by default, with no manual work required. The rebuilt artifacts are signed and attested to the same SLSA Build Level 3 standard as the base images and charts, ensuring a secure and verifiable supply chain.

Customize a Docker Hardened Image

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

You can create customizations using either the DHI CLI or the Docker Hub web interface.

# Prepare a single customization scaffold
$ docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git" \
  > my-customization.yaml

# Prepare a bulk customization scaffold (pipe JSON array via stdin)
$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \
  | docker dhi customization prepare --name "golang with git" --org my-org \
  > my-customization.yaml

# Create a customization
$ docker dhi customization create my-customization.yaml --org my-org

# List customizations
$ docker dhi customization list --org my-org

# Filter customizations by name, repository, or source
$ docker dhi customization list --org my-org --filter git
$ docker dhi customization list --org my-org --repo dhi-golang
$ docker dhi customization list --org my-org --source golang

# Get a customization by ID
$ docker dhi customization get <id> --org my-org

# Update a customization
$ docker dhi customization edit my-customization.yaml --org my-org

# Delete a customization by ID
$ docker dhi customization delete <id> --org my-org

# Delete without confirmation prompt
$ docker dhi customization delete <id> --org my-org --force

resource "dhi_customization" "golang_with_git" {
  repository = "dhi-golang"
  name       = "golang with git"

  contents {
    packages = ["git", "curl"]
  }

  platform {
    os           = "linux"
    architecture = "amd64"
  }
}

Image customization YAML file

When using the CLI, customizations are defined in a YAML file. Use docker dhi customization prepare to generate a scaffold with all available fields and commented-out examples. Edit the file to describe what you want, then pass it to docker dhi customization create.

The file has two parts: a preamble that identifies the customization and its targets, and a configuration section that specifies what to change.

About the id field

The id field is assigned automatically by Docker Hub when you run docker dhi customization create. When creating a new customization, omit id entirely. It is read-only.

To find the ID of an existing customization, run:

$ docker dhi customization list --org my-org

The id appears in the output and in files retrieved with docker dhi customization get <id> --org my-org. It lets docker dhi customization edit identify which customization to update. Scaffolds from docker dhi customization prepare do not include id, and that is expected.

Set targets

The name and targets fields are required in every customization file. The targets array specifies which image versions the customization applies to. Use a single entry for a single-image customization, or multiple entries for a bulk customization that applies the same configuration to several images at once.

name: golang with git

targets:
  - destination: my-org/dhi-golang
    tag_definition_id: golang/alpine-3.23/1.25

Note

When targets has more than one entry, the fields accounts, entrypoint, and cmd are not supported. Including them causes docker dhi customization create to return an error.

Add packages

To install additional OS packages in your customized image, list them under contents.packages. Available packages depend on the base image variant.

contents:
  packages:
    - git
    - curl

Add OCI artifacts

To layer additional files into your customized image, such as custom certificates, internal tools, or configuration files, list OCI artifact images under contents.artifacts.

contents:
  artifacts:
    - name: my-org/my-certs:latest
      includes:
        - etc/ssl/certs
      excludes:
        - etc/ssl/certs/old

For instructions on building an OCI artifact image, see Create an OCI artifact image.

Inject files into the image

To add static files at build time, such as configuration files or startup scripts, use the paths field. Files are added as static content and are not executed during the build.

paths:
  - path: /etc/myconfig
    contents: |
      key=value
    mode: "0644"
    uid: 0
    gid: 0

Configure user accounts

To add users or groups to the image, or to change which user the container runs as, use the accounts field.

Note

Not supported for bulk customizations (multiple targets).

accounts:
  root: true
  runs-as: nonroot
  users:
    - name: nonroot
      uid: 65532
      gid: 65532
  groups:
    - name: nonroot
      gid: 65532
      members:
        - nonroot

Set environment variables

To add or override environment variables in the image, use the environment field. These are merged with the base image's existing environment and do not replace it.

environment:
  MY_VAR: my_value
  DEBUG: "false"

Quote values that a YAML parser would interpret as non-string types, for example "false", "0", and "null".

Set labels and annotations

To add OCI metadata to the image, use labels and annotations. Labels are stored in the image config; annotations are stored in the image manifest. Use OCI standard keys where applicable.

labels:
  org.opencontainers.image.authors: your-email@example.com
  org.opencontainers.image.version: "1.0.0"

annotations:
  org.opencontainers.image.title: Custom hardened image
  org.opencontainers.image.description: Customized Docker Hardened Image

Override entrypoint and command

To change how the container starts, use entrypoint and cmd. These arguments are appended to the base image's existing entrypoint and command.

Note

Not supported for bulk customizations (multiple targets).

entrypoint:
  - /docker-entrypoint.sh

cmd:
  - /bin/bash

Set platforms and compression

To build for multiple architectures, list them under platforms. At least one platform is required.

platforms:
  - linux/amd64
  - linux/arm64

To control layer compression, set compression. ZSTD (the default) offers better compression and faster pulls. Use GZIP for compatibility with older tooling.

compression: ZSTD

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 dhi.io/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.

In order for the OCI artifact to be available in a DHI customization, it must be built and pushed to a repository in the same namespace as the mirrored DHI repository.

If you're customizing a DHI for multiple platforms (such as linux/amd64 and linux/arm64), build your OCI artifact for all the platforms using the --platform flag:

$ docker buildx build --platform linux/amd64,linux/arm64 \
  -t <your-namespace>/my-oci-artifact:latest \
  --push .

This creates a single image manifest that you can use for each platform. The customization build system automatically selects the correct platform variant when building each customized image.

Important

The customization UI will only allow you to select platforms that are available in all OCI artifacts you've added. If a platform is missing from any OCI artifact, you won't be able to select that platform for your customization.

Once pushed to a repository in your organization's namespace, the OCI artifact automatically appears in the customization workflow when you select OCI artifacts to add to your customized Docker Hardened Image.

Best practices for OCI artifacts

Follow these best practices when creating OCI artifacts for DHI customizations:

• Use multi-stage builds: Build or install dependencies in a builder stage, then copy only the necessary files to a FROM scratch final stage. This keeps the OCI artifact minimal and free of unnecessary build tools.

• Include only essential files: OCI artifacts should contain only the files you need to add to the customized image. Avoid including package managers, shells, or other utilities that won't be used in the final image.

• Match target platforms: Build your OCI artifact for all platforms you plan to use in your customizations. Use docker buildx build --platform to create multi-platform images when needed.

• Use specific tags: Tag your OCI artifacts with specific versions or dates (like v1.0 or 20250101) rather than relying solely on latest. This ensures reproducible builds and makes it easier to track which artifacts are used in which customizations.

• Enable immutable tags: Consider enabling immutable tags for your OCI artifact repositories. This prevents accidental overwrites and ensures that each version of your OCI artifact remains unchanged, improving reproducibility and reliability of your customizations.

Customize a DHI Helm chart

You can customize DHI Helm charts to meet your organization's specific needs. Via the Docker Hub web interface, you can modify the image references to reference mirrored images or customized images you've created. This lets you create a custom, securely-built chart with references to images stored in Docker Hub or other private registries. DHI securely packages customized Helm charts that reference your repositories, wherever they are stored, by default.

To customize image references, an organization owner must mirror the DHI chart repository to your organization on Docker Hub.

You can create one chart customization per Helm chart repository. This is different from image customizations, where you can create multiple customizations per repository. If you need to make changes, you can edit your existing customization. Alternatively, you can mirror the same Helm chart repository again and add a new customization to the new mirror.

Note

You can customize Docker Hardened Image charts like any other Helm chart using standard Helm tools and practices, such as a values.yaml file, outside of Docker Hub. The following instructions describe how to customize image references for the chart using the Docker Hub web interface.

To customize a Docker Hardened Image Helm chart after it has been mirrored:

1. Sign in to Docker Hub.

2. Select My Hub.

3. In the namespace drop-down, select your organization that has a mirrored DHI repository.

4. Select Hardened Images > Manage > Mirrored Helm charts.

5. For the mirrored DHI repository you want to customize, select the Name.

6. Select the Customizations tab.

7. Select Create customization.

   At this point, the on-screen instructions will guide you through the customization process.

Helm chart customization YAML file

When using the CLI, Helm chart customizations use the same prepare / create workflow as image customizations, but the configuration section uses reference_mappings instead of image fields.

Use reference_mappings to substitute image references within the chart, for example to point a chart's image references at your mirrored DHIs.

name: use mirrored images

targets:
  - destination: my-org/dhi-haproxy-chart
    tag_definition_id: haproxy/helm/1

reference_mappings:
  - from: dhi/haproxy
    to: my-org/dhi-haproxy

Monitor customization builds

After creating a customization, you can track build status and view logs through Docker Hub or the DHI CLI.

$ docker dhi customization build list <customization-id> --org my-org

$ docker dhi customization build get <customization-id> <build-id> --org my-org

$ docker dhi customization build logs <customization-id> <build-id> --org my-org

Edit or delete a customization

$ docker dhi customization edit my-customization.yaml --org my-org

$ docker dhi customization delete <id> --org my-org
$ docker dhi customization delete <id> --org my-org --force