dhi: add customizations

Signed-off-by: Craig <craig.osterhout@docker.com>

Author: craig-osterhout

content/manuals/dhi/features/flexible.md

@@ -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.
+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
 
@@ -30,15 +31,27 @@ freely choose the best tag for each use case without incurring additional cost.
 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.
+
 ## 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.

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

@@ -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

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

@@ -0,0 +1,130 @@
+---
+title: Customize a Docker Hardened Image
+linkTitle: Customize an image
+weight: 25
+keywords: debug, hardened images, DHI, customize, certificate, artififact
+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
+
+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
+      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
+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:
+
+```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.

data/redirects.yml

@@ -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/