Skip to content

dhi: add customizations #23035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

dhi: add customizations #23035

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5ee2eb4
dhi: add customizations
craig-osterhout Jul 8, 2025
e88c1a9
clarify packages and oci artifacts steps
craig-osterhout Jul 10, 2025
f3e1891
polish wording
craig-osterhout Jul 10, 2025
c4f8a1e
add any user can mirror
craig-osterhout Jul 10, 2025
ef05d2b
remove org name in example
craig-osterhout Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 22 additions & 9 deletions content/manuals/dhi/features/flexible.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
---
title: Flexible, repository-based pricing
title: Flexibility through pricing and customization
linktitle: Flexibility
description: Understand how Docker Hardened Images give you cost control by charging only for what you mirror and use.
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model
description: Learn how Docker Hardened Images give you control over costs and image behavior through repository-based pricing and secure customization.

Check failure on line 4 in content/manuals/dhi/features/flexible.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'repo'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'repo'?", "location": {"path": "content/manuals/dhi/features/flexible.md", "range": {"start": {"line": 4, "column": 102}}}, "severity": "ERROR"}

Check warning on line 4 in content/manuals/dhi/features/flexible.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'repository' instead of 'repo'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'repository' instead of 'repo'", "location": {"path": "content/manuals/dhi/features/flexible.md", "range": {"start": {"line": 4, "column": 102}}}, "severity": "INFO"}
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model, customize hardened image
weight: 30
---

Docker Hardened Images are designed not only for security and compliance, but
also for operational and financial efficiency. With a model that charges per
repository, you get precise control over what you use and what you pay for.
repository and tooling that lets you customize images securely, you gain both
cost control and configuration flexibility.

## Repository mirroring on your terms

Expand All @@ -30,15 +31,27 @@
This flexibility allows teams to adopt secure images without being limited by
billing complexity or image count.

## Customize images to fit your environment

In addition to cost flexibility, Docker Hardened Images let you securely
customize images before use. You can add your own packages, tools, certificates,
and configuration files using a guided customization workflow in Docker Hub.
These customizations are securely built and signed, so they integrate with your
compliance and CI/CD policies.

Check warning on line 40 in content/manuals/dhi/features/flexible.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'CD' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'CD' has no definition.", "location": {"path": "content/manuals/dhi/features/flexible.md", "range": {"start": {"line": 40, "column": 19}}}, "severity": "WARNING"}

## Share access across your team

Once a repository is mirrored, anyone in your organization can pull, verify,
scan, and run images from it. There are no extra charges based on usage volume.
You mirror what you need, and your teams use it freely.

## Cost efficiency for platform teams
## Cost and operational efficiency for platform teams

The Docker Hardened Images model simplifies budgeting for platform and security
teams. Instead of tracking usage at the image or tag level, you manage spend
through the repositories you mirror. And since you can customize images within
Docker Hub itself, everything is in one place, reducing complexity and
operational overhead.

This model simplifies budgeting for platform and security teams. Rather than
tracking usage at the individual image or tag level, you manage your spend
through the repositories you control, aligning security enforcement, team access,
and cost in one place.
By aligning repository mirroring, team access, image customization, and cost,
Docker Hardened Images help you build securely and operate efficiently.
4 changes: 4 additions & 0 deletions content/manuals/dhi/how-to/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ params:
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
icon: compare_arrows
link: /dhi/how-to/mirror/
- title: Customize a Docker Hardened Image
description: Learn how to customize a DHI to suit your organization's needs.
icon: settings
link: /dhi/how-to/customize/
- title: Use a Docker Hardened Image
description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.
icon: play_arrow
Expand Down
130 changes: 130 additions & 0 deletions content/manuals/dhi/how-to/customize.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
---
title: Customize a Docker Hardened Image
linkTitle: Customize an image
weight: 25
keywords: debug, hardened images, DHI, customize, certificate, artififact

Check failure on line 5 in content/manuals/dhi/how-to/customize.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'artififact'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'artififact'?", "location": {"path": "content/manuals/dhi/how-to/customize.md", "range": {"start": {"line": 5, "column": 64}}}, "severity": "ERROR"}

Check warning on line 5 in content/manuals/dhi/how-to/customize.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'DHI' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'DHI' has no definition.", "location": {"path": "content/manuals/dhi/how-to/customize.md", "range": {"start": {"line": 5, "column": 35}}}, "severity": "WARNING"}
description: Learn how to customize a Docker Hardened Images (DHI).
---

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, you must first
[mirror](./mirror.md) the DHI repository to your organization.

## Customize a Docker Hardened Image

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it make sense to add in some screenshots here? The UI was deployed to production yesterday, so these will be available now.

Copy link
Contributor Author

@craig-osterhout craig-osterhout Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the customization UI itself is intuitive/well-guided and screenshots probably won't add much for comprehension.

The only things I can think to use screenshots for are:

  • Initially getting to the guided UI. The un-guided steps 1 through 6.
  • Subtle marketing to show users, before they buy/try, how easy it is.

@Bkblodget, are any of those the purpose you had in mind, or something else?

To customize a Docker Hardened Image, follow these steps:

1. Sign in to [Docker Hub](https://hub.docker.com).
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has a mirrored DHI
repository.
4. Select the mirrored DHI repository.
5. Select the **Customizations** tab.
6. 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.

7. Select the image version you want to customize.
8. Add packages.

1. In the **Packages** drop-down, select the packages you want to add to the
image.
2. In the **OCI artifacts** drop-down select the OCI artifacts you want to
add to the 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

Check warning on line 41 in content/manuals/dhi/how-to/customize.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'CA' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'CA' has no definition.", "location": {"path": "content/manuals/dhi/how-to/customize.md", "range": {"start": {"line": 41, "column": 51}}}, "severity": "WARNING"}
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](#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 can further select paths to include or exclude from
each OCI artifact image. This allows you to control which files are
included in the final customized image.

> [!NOTE]
>
> When necessary files are overwritten, the image build still
> succeeds, but you may have issues when running the image.

9. 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`](/reference/dockerfile/#entrypoint) and
[`CMD`](/reference/dockerfile/#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](/reference/dockerfile/#user) to run the images as.
7. Specify the [environment variables](/reference/dockerfile/#env) and their
values that the image will contain.
8. Add [annotations](/build/metadata/annotations/) to the image.
9. Add [labels](/reference/dockerfile/#label) to the image.
10. 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:

1. Sign in to [Docker Hub](https://hub.docker.com).
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has a mirrored DHI.
4. Select the mirrored DHI repository.
5. Select the **Customizations** tab.
6. Select **Edit** to edit the customization, or select the trashcan icon to
delete the customization.
7. 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

Check warning on line 101 in content/manuals/dhi/how-to/customize.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'CA' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'CA' has no definition.", "location": {"path": "content/manuals/dhi/how-to/customize.md", "range": {"start": {"line": 101, "column": 78}}}, "severity": "WARNING"}

Check warning on line 101 in content/manuals/dhi/how-to/customize.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'CA' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'CA' has no definition.", "location": {"path": "content/manuals/dhi/how-to/customize.md", "range": {"start": {"line": 101, "column": 42}}}, "severity": "WARNING"}
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

Check warning on line 103 in content/manuals/dhi/how-to/customize.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'CA' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'CA' has no definition.", "location": {"path": "content/manuals/dhi/how-to/customize.md", "range": {"start": {"line": 103, "column": 52}}}, "severity": "WARNING"}
extracted into a minimal final image:

```dockerfile
# syntax=docker/dockerfile:1

FROM yourorg/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.
7 changes: 7 additions & 0 deletions data/redirects.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,3 +349,10 @@
- /go/permissions/
"/desktop/setup/install/mac-permission-requirements/#binding-privileged-ports":
- /go/port-mapping/

# Docker Hardened Images (DHI)
"/dhi/how-to/customize/":
- /go/dhi-customization/

"/dhi/how-to/customize/#create-an-oci-artifact-image":
- /go/dhi-customization-artifacts/