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 that provide features such as Federal Information Processing Standards (FIPS) and Security Technical Implementation Guides (STIG) compliance variants, customization capabilities, and SLA-backed support. With DHI Select and Enterprise, you can mirror images to a private Docker organization.

Upstream configuration

Create Docker Upstream Form
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.
Verify SSL CertificatesIf 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.
Authentication (optional)Optional credentials that can be provided if the upstream is not publicly accessible.

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)Optional key-value headers that can be passed to upstreams with each request.

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 a pre-configured DHI upstream:

      1. Select the pre-configured Docker Hardened Images (Community) format.

      2. Click + Add 1 upstream.

        Your DHI upstream appears on the Upstream registries section of the Sources tab.

    • To define settings for your upstream:

      1. Click Configure your own.
      2. Select the Docker format.
      3. In the Name field, enter a descriptive name for the upstream.
      4. In the Priority field, specify a priority for the upstream. For more information about upstream priority, see Upstream concepts: Priority.
      5. In the Proxy URL field, enter the DHI registry URL:
        • For free tier DHI Community images, enter https://dhi.io.
        • For mirrored DHI Select or Enterprise images, you can pull through either https://dhi.io, or a standard Docker Hub integration by specifying your Docker organization in the image path (mydockerorg/dhi-node:latest).
      6. Under Package delivery, select either Proxy only or Cache and proxy.
      7. Click Additional options.
      8. Under Source type, select Public or Private.
        • Public: Credentials are not required for public sources.
        • Private:
          1. (Optional) Under Authentication type, select Basic Auth and enter a Username and Password.
      9. (Optional) In the Headers section, add key-value headers to pass to the upstream with each request.
      10. (Optional) Select the Verify SSL certificate option to ensure that SSL certificates are verified.
      11. Click + Add upstream.

      Your DHI upstream appears on the Upstream registries section of the Sources tab.

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. Ensure that Docker is installed on your system. For more information about installing Docker, see the Docker: Install Docker Engine documentation.
  3. Open a terminal.
  4. Log in to Docker with your Cloudsmith username and token: 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: docker pull docker.cloudsmith.io/WORKSPACE/REPOSITORY/node:20-alpine3.22
  6. Check your Cloudsmith repository to find the newly added DHI node image.