Cloudsmith Documentation/Help Hub

Welcome to the Cloudsmith Documentation/Help Hub. You'll find comprehensive guides and documentation to help you start working with Cloudsmith as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Docker Registry

Cloudsmith provides public & private registries for Docker images

Docker is an ecosystem that is used to run packaged software known as containers. A container image is bundled with all of the software and configured required to run as an independent process (or collection of processes), and an executing container is isolated from other containers and processes.

Docker provides the concept of the registry as a storage service for storing and distributing image containers for use. The official one of which is DockerHub, which is owned and operated by Docker itself.

Cloudsmith provides a fully-fledged Docker registry with full compatibility for current and future versions of the Docker engine and container image formats. With Cloudsmith you'll be able to push, pull, inspect and manage container images, privately and publicly.

All of this is provided with the standard functionality and features that are offered in the Cloudsmith platform, such as collaboration, advanced permissioning, whitelabelled distribution, multi-tenacy with other packaging formats, etc.

For more information on Docker, please see:

  • Docker: The official website for Docker (the company and product).
  • DockerHub: The official public registry for Docker repositories.
  • Docker Article: The Wikipedia article on Docker.
Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo pre-configured).

Differences from Docker

For clarity, it's important to note some of the differences between a registry such as DockerHub, and a Cloudsmith Docker registry. These are both naming and functional in nature.

Naming Differences

Docker defines the following names (this is not the official wording):

  • Layer: A blob (big object of bytes) containing software and configuration.
  • Image: A collection of Docker layers plus metadata that represent an application.
  • Container: A running instance of a Docker image in-memory.
  • Repository: A collection of Docker images, separated by hashref and version tags.
  • Registry: A collection of all Docker repositories, separated by namespaces.

For comparison purposes, where terms differ from Cloudsmith:

  • Package: A specific identifiable and versionable artifact.
  • Repository: A collection of versionable artifacts, with multiple allowed per account.

Therefore, based on the above, the following terms are equivalent:

Docker Term

Cloudsmith Term

Image

Package

Registry

Repository

For consistency, the Docker terms will be used within all of the Docker-related documentation but please be aware of the differences if looking at documentation elsewhere.

Functionality Differences

We have attempted to achieve absolute compatibility at the wire (API) level with DockerHub and the Docker registration specification (2.0). The functionality differs in how the registry itself is treated.

Referring to the naming differences section above, every Cloudsmith account can have multiple Cloudsmith repositories. Each Cloudsmith repository is an individual Docker registry in its own right and will require a different login in order to push/pull images for it.

As such, it is also not possible to have a global registry of all images on Cloudsmith. This may change in the future as we introduce different forms of Cloudsmith repositories and groupings.

In the following examples:

Identifier

Description

OWNER

Your Cloudsmith account name or organisation name (namespace)

REGISTRY

Your Cloudsmith Repository name (also called "slug")

TOKEN

Your Cloudsmith Entitlement Token (see Entitlements for more details)

USERNAME

Your Cloudsmith username

PASSWORD

Your Cloudsmith password

API-KEY

Your Cloudsmith API Key

IMAGE_NAME

The name of your Docker image

TAG

A tag for your Docker image


Upload an Image

Publish via Docker

The endpoint for the native Docker API is:

https://docker.cloudsmith.io/v2/OWNER/REGISTRY/

Or if you're referring to it from docker commands:

docker.cloudsmith.io/OWNER/REGISTRY

In order to authenticate for native publishing, you'll need use docker login:

docker login docker.cloudsmith.io

You will be prompted for your Username and Password. Enter your Cloudsmith username and your Cloudsmith API Key.

To publish an image to a Cloudsmith-based Docker registry, you first need to tag your image:

docker tag IMAGE_NAME:TAG docker.cloudsmith.io/OWNER/REGISTRY/IMAGE_NAME:TAG

Example:

docker tag your-image:latest docker.cloudsmith.io/org/repo/your-image:latest

You can then publish the tagged image using docker push:

docker push docker.cloudsmith.io/OWNER/REGISTRY/IMAGE_NAME:TAG

Upload via the Cloudsmith CLI or Website

To upload via the Cloudsmith CLI or Website. you need to export your Docker image first. You can do this with:

docker save -o IMAGE_NAME.docker IMAGE_NAME:TAG

This exports the full contents of the image, including all metadata and layers.

Upload via Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Docker image via the Cloudsmith CLI is:

cloudsmith push docker OWNER/REGISTRY IMAGE_NAME.docker

Example:

cloudsmith push docker org/repo your-image.docker

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.


Download / Pull an Image

Setup

Public Registries

For public registries, no further setup is needed as authentication is not required.

Private Registries

πŸ“˜

Private Registries require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

You need to authenticate via docker login to pull images:

docker login docker.cloudsmith.io
Username: OWNER/REGISTRY
Password: TOKEN

Login Succeeded
docker login docker.cloudsmith.io
Username: OWNER/REGISTRY
Password: PASSWORD

Login Succeeded
docker login docker.cloudsmith.io
Username: OWNER/REGISTRY
Password: API-KEY

Login Succeeded
docker login docker.cloudsmith.io
Username: OWNER/REGISTRY
Password: TOKEN

Login Succeeded

Pull an Image

Pulling (downloading) an image from the Cloudsmith Docker registry can be done using the standard docker pull command:

docker pull docker.cloudsmith.io/OWNER/REGISTRY/IMAGE_NAME:TAG

To refer to this image after pulling in a Dockerfile, specify the following:

FROM docker.cloudsmith.io/OWNER/REGISTRY/IMAGE_NAME:TAG

Security Scanning

When a Docker image is uploaded or resynchronized, it is scanned for any known vulnerabilities

You can view the details of any identified vulnerabilities using the "Vulnerabilities" tab on the detail view for the image:

Docker Vulnerabilities Tab

Data Sources

Current Limitations

The Cloudsmith Docker registry implementation currently has the following limitations:

  • Transparent proxying of images from an upstream (such as DockerHub) is currently not supported.
  • Remote layer mounting (for non-distributable layers, such as Windows) is currently not supported.
  • Storage is charged for each image, but we'll offer a better model for this soon.
  • Digests for images will not match those pushed to Docker Hub (but layers will match).
  • Digests for offline image uploads (via docker save) will not match those from docker push.

Unless otherwise specified we'll be working on removing these limitations in a near-future release.

Follow our roadmap for development progress.

Upstream Proxying / Caching

Not Supported

Key Signing Support

RSA Index

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated 2 months ago


Docker Registry


Cloudsmith provides public & private registries for Docker images

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.