docs: clarify dhi.io proxy access in the mirroring guide (#26232)

## Description

The third-party mirroring guide describes image layers as stored on
`dhi.io`, which makes it unclear why the examples use Docker Hub for
images and the Scout registry for attestations.

Clarify that `dhi.io` provides access to DHI catalog images and their
signed attestations, while customer mirrors and customized images in
organization repositories are accessed through Docker Hub. This explains
why the examples copy images from Docker Hub and attestations from
`registry.scout.docker.com` into the same destination repository.
Copying only the image does not preserve its attestations.

The proxy's repository routing rejects names containing `/` and maps
accepted names into the `dhi/` namespace: [routing
implementation](https://github.com/atomisthq/dhi-proxy/blob/e47c68d6473b2b45a4aeb3be55808eee58902732/internal/proxy/middleware.go#L161-L188).
The public [image reference
documentation](https://docs.docker.com/dhi/how-to/use/#pull-run-and-reference-dhis)
also distinguishes catalog references on `dhi.io` from organization
repositories on Docker Hub.

## Reviews

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

## Validation

- `npx --no-install rumdl fmt content/manuals/dhi/how-to/mirror.md`
- `scripts/lint.sh content/manuals/dhi/how-to/mirror.md` with
repository-pinned rumdl 0.2.49 and Vale 3.17.0: no errors, warnings, or
suggestions
- `git diff --check`

This is a prose-only change. The mirroring commands are unchanged. A
full site build was not run.

---------

Signed-off-by: Brian Rubinton <brian.rubinton@docker.com>
This commit is contained in:
Brian J. Rubinton authored and GitHub committed 2026-09-30 13:30:26 -07:00
1 parent b3c1c9d404
commit 5c666918fc
1 file changed
+14 -4
+14 -4
View File
@@ -232,10 +232,20 @@ You can use any standard workflow to mirror the image, such as the
API](/reference/api/registry/latest/), third-party registry tools, or CI/CD
automation.
However, to preserve the full security context, including attestations, you must
also mirror its associated OCI artifacts. DHI repositories store the image
layers on `dhi.io` (or `docker.io` for customized images) and the signed
attestations in a separate registry (`registry.scout.docker.com`).
Mirroring an image requires copying both the image and its associated signed
attestations, including SBOMs, provenance, and VEX. Copying only the image does
not preserve these attestations in your destination registry.
The `dhi.io` proxy provides access to DHI catalog images and their associated
attestations. It retrieves image manifests and layers from Docker Hub, and
attestations from `registry.scout.docker.com`.
Customer mirrors and customized images are accessed through your organization's
repositories on Docker Hub. These repositories are not available through
`dhi.io`. The following examples therefore use two source locations:
`docker.io/<your-org>/<repository>` for the image and
`registry.scout.docker.com/<your-org>/<repository>` for its attestations. Both
are copied into the same repository in your destination registry.
To copy both, you can use [`regctl`](https://regclient.org/cli/regctl/), an
OCI-aware CLI that supports mirroring images along with attached artifacts such