Skip to content

Commit 4375b63

Browse files
craig-osterhoutcraig-osterhout
committed
dhi: add customizations
Signed-off-by: Craig <craig.osterhout@docker.com>
1 parent f48b544 commit 4375b63

File tree

4 files changed

+171
-17
lines changed

4 files changed

+171
-17
lines changed

‎content/manuals/dhi/features/flexible.md

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,25 @@
11
---
2-
title: Flexible, repository-based pricing
2+
title: Flexibility through pricing and customization
33
linktitle: Flexibility
4-
description: Understand how Docker Hardened Images give you cost control by charging only for what you mirror and use.
5-
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model
4+
description: Learn how Docker Hardened Images give you control over costs and image behavior through repository-based pricing and secure customization.
5+
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model, customize hardened image
66
weight: 30
77
---
88

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

13-
## Repository mirroring on your terms
14+
## Mirror only what you need
1415

1516
With Docker Hardened Images, you mirror entire repositories, each giving you
16-
access to all supported tags, variants, and versions. You can choose which
17-
repositories to mirror based on your needs.
17+
access to all supported tags, variants, and versions. You're in control of what
18+
you use and what you pay for.
1819

1920
This flexibility allows your organization to adapt as projects evolve, whether
20-
you're spinning up new environments, consolidating runtimes, or managing costs
21-
over time, without worrying about per-image or per-pull fees.
21+
you're spinning up new environments, consolidating runtimes, or managing
22+
costs, without worrying about per-image or per-pull fees.
2223

2324
## Access all variants and versions
2425

@@ -27,18 +28,30 @@ supported tags in that repository, including multiple versions, base
2728
distributions (such as Alpine and Debian), and dev/runtime variants. You can
2829
freely choose the best tag for each use case without incurring additional cost.
2930

30-
This flexibility allows teams to adopt secure images without being limited by
31-
billing complexity or image count.
31+
This flexibility supports secure image adoption without the complexity of
32+
tracking image count or tag usage.
33+
34+
## Customize images to fit your environment
35+
36+
In addition to cost flexibility, Docker Hardened Images let you securely
37+
customize images before use. You can add your own packages, tools, certificates,
38+
and configuration files using a guided customization workflow in Docker Hub.
39+
These customizations are securely built and signed, so they integrate with your
40+
compliance and CI/CD policies.
3241

3342
## Share access across your team
3443

3544
Once a repository is mirrored, anyone in your organization can pull, verify,
3645
scan, and run images from it. There are no extra charges based on usage volume.
37-
You mirror what you need, and your teams use it freely.
46+
You mirror what you need, and your teams use it.
47+
48+
## Cost and operational efficiency for platform teams
3849

39-
## Cost efficiency for platform teams
50+
The Docker Hardened Images model simplifies budgeting for platform and security
51+
teams. Instead of tracking usage at the image or tag level, you manage spend
52+
through the repositories you mirror. And since you can customize images within
53+
Docker Hub itself, everything is in one place, reducing complexity and
54+
operational overhead.
4055

41-
This model simplifies budgeting for platform and security teams. Rather than
42-
tracking usage at the individual image or tag level, you manage your spend
43-
through the repositories you control, aligning security enforcement, team access,
44-
and cost in one place.
56+
By aligning repository mirroring, team access, image customization, and cost,
57+
Docker Hardened Images help you build securely and operate efficiently.

‎content/manuals/dhi/how-to/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ params:
1212
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
1313
icon: compare_arrows
1414
link: /dhi/how-to/mirror/
15+
- title: Customize a Docker Hardened Image
16+
description: Learn how to customize a DHI to suit your organization's needs.
17+
icon: settings
18+
link: /dhi/how-to/customize/
1519
- title: Use a Docker Hardened Image
1620
description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.
1721
icon: play_arrow

‎content/manuals/dhi/how-to/customize.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: Customize a Docker Hardened Image
3+
linkTitle: Customize an image
4+
weight: 25
5+
keywords: debug, hardened images, DHI, customize, certificate, artififact
6+
description: Learn how to customize a Docker Hardened Images (DHI).
7+
---
8+
9+
You can customize a Docker Hardened Image (DHI) to suit your specific needs
10+
using the Docker Hub UI. This allows you to select a base image, add packages,
11+
add artifacts, and configure settings. In addition, the build pipeline ensures that
12+
your customized image is built securely and includes attestations.
13+
14+
To add a customized Docker Hardened Image to your organization, you must first
15+
[mirror](./mirror.md) the DHI repository to your organization.
16+
17+
## Customize a Docker Hardened Image
18+
19+
To customize a Docker Hardened Image, follow these steps:
20+
21+
1. Sign in to [Docker Hub](https://hub.docker.com).
22+
2. Select **My Hub**.
23+
3. In the namespace drop-down, select your organization that has a mirrored DHI
24+
repository.
25+
4. Select the mirrored DHI repository.
26+
5. Select the **Customizations** tab.
27+
6. Select **Create customization**.
28+
29+
At this point, the on-screen instructions will guide you through the
30+
customization process. You can continue with the following steps for more
31+
details.
32+
33+
7. Select the image version you want to customize.
34+
8. Add packages.
35+
36+
1. In the **Packages** drop-down, select the packages you want to add to the
37+
image.
38+
2. In the **OCI artifacts** drop-down select the OCI artifacts you want to
39+
add to the image. The OCI artifacts are images that you have previously
40+
built and pushed to a repository in the same namespace as the mirrored
41+
DHI. For example, you can add a custom root CA certificate or a another
42+
image that contains a tool you need, like adding Python to a Node.js
43+
image. For more details on how to create an OCI artifact image, see
44+
[Create an OCI artifact image](#create-an-oci-artifact-image).
45+
46+
When combining images that contain directories and files with the same
47+
path, images later in the list will overwrite files from earlier images.
48+
To manage this, you can further select paths to include or exclude from
49+
each OCI artifact image. This allows you to control which files are
50+
included in the final customized image.
51+
52+
> [!NOTE]
53+
>
54+
> When necessary files are overwritten, the image build still
55+
> succeeds, but you may have issues when running the image.
56+
57+
9. Select **Next: Configure** and then configure the following options.
58+
59+
1. Specify a suffix that is appended to the customized image's tag. For
60+
example, if you specify `custom` when customizing the `dhi-python:3.13`
61+
image, the customized image will be tagged as `dhi-python:3.13_custom`.
62+
2. Select the platforms you want to build the image for.
63+
3. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) and
64+
[`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
65+
arguments are appended to the base image's entrypoint and command.
66+
4. Specify the users to add to the image.
67+
5. Specify the user groups to add to the image.
68+
6. Select which [user](/reference/dockerfile/#user) to run the images as.
69+
7. Specify the [environment variables](/reference/dockerfile/#env) and their
70+
values that the image will contain.
71+
8. Add [annotations](/build/metadata/annotations/) to the image.
72+
9. Add [labels](/reference/dockerfile/#label) to the image.
73+
10. Select **Create Customization**.
74+
75+
A summary of the customization appears. It may take some time for the image
76+
to build. Once built, it will appear in the **Tags** tab of the repository,
77+
and your team members can pull it like any other image.
78+
79+
## Edit or delete a Docker Hardened Image customization
80+
81+
To edit or delete a Docker Hardened Image customization, follow these steps:
82+
83+
1. Sign in to [Docker Hub](https://hub.docker.com).
84+
2. Select **My Hub**.
85+
3. In the namespace drop-down, select your organization that has a mirrored DHI.
86+
4. Select the mirrored DHI repository.
87+
5. Select the **Customizations** tab.
88+
6. Select **Edit** to edit the customization, or select the trashcan icon to
89+
delete the customization.
90+
7. Follow the on-screen instructions to complete the edit or deletion.
91+
92+
## Create an OCI artifact image
93+
94+
An OCI artifact image is a Docker image that contains files or directories that
95+
you want to include in your customized Docker Hardened Image (DHI). This can
96+
include additional tools, libraries, or configuration files.
97+
98+
When creating an image to use as an OCI artifact, it should ideally be as
99+
minimal as possible and contain only the necessary files.
100+
101+
For example, to distribute a custom root CA certificate as part of a trusted CA
102+
bundle, you can use a multi-stage build. This approach registers your
103+
certificate with the system and outputs an updated CA bundle, which can be
104+
extracted into a minimal final image:
105+
106+
```dockerfile
107+
# syntax=docker/dockerfile:1
108+
109+
FROM yourorg/dhi-bash:5-dev AS certs
110+
111+
ENV DEBIAN_FRONTEND=noninteractive
112+
113+
RUN mkdir -p /usr/local/share/ca-certificates/my-rootca
114+
COPY certs/rootCA.crt /usr/local/share/ca-certificates/my-rootca
115+
116+
RUN update-ca-certificates
117+
118+
FROM scratch
119+
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
120+
```
121+
122+
You can follow this pattern to create other OCI artifacts, such as images
123+
containing tools or libraries that you want to include in your customized DHI.
124+
Install the necessary tools or libraries in the first stage, and then copy the
125+
relevant files to the final stage that uses `FROM scratch`. This ensures that
126+
your OCI artifact is minimal and contains only the necessary files.
127+
128+
Build and push the OCI artifact image to a repository in your organization's
129+
namespace and it automatically appears in the customization workflow when you
130+
select the OCI artifacts to add to your customized Docker Hardened Image.

‎data/redirects.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,3 +349,10 @@
349349
- /go/permissions/
350350
"/desktop/setup/install/mac-permission-requirements/#binding-privileged-ports":
351351
- /go/port-mapping/
352+
353+
# Docker Hardened Images (DHI)
354+
"/dhi/how-to/customize/":
355+
- /go/dhi-customization/
356+
357+
"/dhi/how-to/customize/#create-an-oci-artifact-image":
358+
- /go/dhi-customization-artifacts/

0 commit comments

Comments
 (0)