Documentation
Book a demo

Integrations

Integrating with Docker Hardened Images

Docker Hardened Images (DHI), are minimal, secure, and production-ready container base and application images maintained by Docker. Designed to reduce vulnerabilities and simplify compliance, DHI integrate easily into your existing Docker-based workflows with little to no retooling required.

You can retrieve these images through Cloudsmith by configuring an upstream to the DHI registry.

Docker offers a free DHI Community registry (dhi.io) that contains developer images, as well as DHI Select and Enterprise tiers. With DHI Select and Enterprise, you can mirror images to a private Docker organization.

Upstream configuration

Form FieldDescription
NameA descriptive name for this upstream source. A shortened version of this name will be used for tagging cached packages retrieved from this upstream.
PriorityThe weighting of the Upstream source. Upstream sources are selected for resolving requests by sequential order (1..n), followed by creation date.
Proxy URLThe URL for this upstream source. This must be a fully qualified URL including any path elements required to reach the root of the repository.
Proxy OnlyProxy requests through to upstream sources in order to match assets that are not present in this repository.
Cache and ProxyProxy the initial request for an asset through to the upstream source and then store (cache) resolved assets in this repository for future requests.
AuthenticationSelect the authentication method required by this upstream. If the upstream does not require credentials, select None from the dropdown.

Note

If a Docker Hub or DHI upstream is created without authentication credentials, it will authenticate by using a Cloudsmith-managed Organization Access Token (OAT). This gives you a higher rate limit than fully anonymous access.

Your workspace name will be shared with Docker so that they can attribute usage to the originating workspace.
Headers (optional, under Additional options)Optional key-value headers that can be passed to upstreams with each request.
Verify SSL Certificates (under Additional options)If enabled, SSL certificates are verified when requests are made to this upstream. We recommend leaving this enabled for all public sources to help mitigate Man-In-The-Middle (MITM) attacks.

Adding the DHI registry as an upstream

You can integrate the DHI registry into your Cloudsmith account by adding a DHI upstream.

DHI Select and Enterprise

To access the DHI Select or Enterprise tiers, you must configure the DHI registry as a private upstream with your Docker Hub credentials.

  1. In your Cloudsmith repository, go to the Sources tab.
  2. If you have existing upstreams configured, click + Configure new upstream.
    • To add pre-configured DHI Community images:
      1. Select the Pre-configured tab.
      2. Select the Docker Hardened Images (Community) format.
      1. Click + Add 1 upstream. Your DHI upstream appears on the Upstream registries section of the Sources tab.
    • To add DHI Select or Enterprise images:
      1. In the modal, select the Hardened images tab.
      2. Click the Docker Hardened Images card.
      1. Select the Select/Enterprise tier.
      2. In the Name field, enter a descriptive name for the upstream.
      3. In the Priority field, specify a priority for the upstream. For more information about upstream priority, see Upstream concepts: Priority.
      4. The Proxy URL field is pre-filled with the DHI registry URL: https://dhi.io.
      5. Under Package delivery, select Cache and proxy.
      6. Under Authentication, select Basic Auth and enter your Docker Hub username and password.
      7. Click Additional options.
      8. (Optional) In the Headers section, add key-value headers to pass to the upstream with each request.
      9. Click + Add upstream. Your DHI upstream appears on the Upstream registries section of the Sources tab.

Mirrored DHI Select or Enterprise images

You can pull mirrored DHI Select or Enterprise images through https://dhi.io or a standard Docker Hub integration by specifying your Docker organization in the image path (mydockerorg/dhi-node:latest).

Pull a DHI image with Docker native tooling

To pull the node Docker Hardened Image into Cloudsmith after you've configured your Cloudsmith upstream for DHI:

  1. Configure a Cloudsmith upstream for DHI by using the instructions in Adding the DHI registry as an upstream.
  2. Verify Docker is installed and running.
  3. Open a terminal.
  4. Log in to Docker using your Cloudsmith username and token:
    bash
    docker login docker.cloudsmith.io
  5. Pull the DHI node image by running the following command, replacing WORKSPACE and REPOSITORY with your Cloudsmith workspace and repository:
    bash
    docker pull docker.cloudsmith.io/WORKSPACE/REPOSITORY/node:20-alpine3.22
  6. Verify the image appears in the Cloudsmith repository.