Documentation
Book a demo

Integrations

Integrating with Docker Hub

Docker Hub is the official registry (provided by Docker, Inc.) that allows you to find and share Docker-format container images.

It's the world's largest repository of container images, with an array of content sources including container community developers, open source projects, and independent software vendors (ISV) building and distributing their code in containers.

You can retrieve these images through Cloudsmith by configuring an upstream to Docker Hub.

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.
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 Docker Hub as an upstream

You can integrate the Docker Hub registry into your Cloudsmith account to begin proxying and caching images from Docker Hub:

  1. In your Cloudsmith repository, go to the Sources tab.
  2. Click + Configure upstream.

    • To add a pre-configured Docker Hub upstream:

      1. Select the pre-configured Docker Hub format.

      2. Click + Add 1 upstream.

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

    • To define settings for your upstream:

      1. Click Manual setup.
      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 Docker Hub registry URL: https://index.docker.io.
      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 Docker upstream appears on the Upstream registries section of the Sources tab, and your account is ready to proxy and cache images from Docker Hub through Cloudsmith.

Warning

If you have a Docker upstream configured, please be aware of the following behaviors when making requests against the Docker API v2 endpoints:

  • Tags/List: All tags from the upstream are returned, not just local Cloudsmith tags.
  • Manifests: This will trigger a cache of the referenced image to your Cloudsmith repository.

Iterating through a list of tags to fetch manifests will trigger automatic caching for every image. This can result in hundreds or thousands of cached images, significantly increasing artifact storage consumption and associated costs.