Raw Repository

Cloudsmith supports "Raw" files. Any file, any extension, suitable for datasets, images or whatever you want to throw at it. You get all the benefits of a Cloudsmith repository such as CLI uploads for automation, fine-grained access controls and logging/statistics (among others) - but for any file type at all.

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/rsa-key pre-configured).

📘

RAW file support is not available on the Core (Free) Plan. Please see our pricing page for full details of features included at each plan level

In the following examples:

Upload a File

📘

When you upload raw package, you can specify a package name with --name via the CLI, or via the Web UI upload form.

If you specify a name that exactly matches the package filename, this is treated as if a name was not specified and the resulting download links will follow the format for a package that was uploaded without a name.

Upload via the Cloudsmith CLI

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

The command to upload via the Cloudsmith CLI is:

cloudsmith push raw OWNER/REPOSITORY FILENAME

Example:

cloudsmith push raw your-account/your-repo file.zip

Upload via Cloudsmith Website

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

Download a Package

Download via Website UI

Public Repositories

When logged into Cloudsmith via a Web Browser, there's a green "Download" button that provides a link to download a raw package on the package details page:

Private Repositories

For downloading from a private repository via the Website UI, you can use the green download button to download a raw package using the default Entitlement Token for the repository. You can also use the dropdown arrow beside the "Download" button to pick a different way of authenticating for the download.

Download via Command Line

To download a Raw package, you'll need to fetch uploaded files using a well-crafted URL. You can find the specific URL for a raw package from the Cloudsmith CLI, with the cloudsmith list packages command and adding -F pretty_json. The package URL is listed in the JSON output as cdn_url:

This URL is in the following formats; it varies based on if you uploaded the raw package with a package name, a version, both or none:

Public Repositories

https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/versions/VERSION_NO/FILENAME

https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/names/NAME/versions/VERSION_NO/FILENAME

https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/names/NAME/files/FILENAME

https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/files/FILENAME

Some example curl commands to download a raw package from a public repository:

A package with no package name or version specified at upload

curl -1sLf -O 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/files/FILENAME'

A specific version of a package

curl -1sLf -O 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/versions/VERSION_NO/FILENAME'

The latest version of the package

curl -1sLf -O 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/versions/latest/FILENAME'

Private Repositories

📘

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

The download URL will differ depending on what authentication type you choose to use.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs.

Raw Package uploaded with a version number:

https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/versions/VERSION_NO/FILENAME

https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/versions/VERSION_NO/FILENAME'

Raw Package uploaded with a package name and version number:

https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/names/NAME/versions/VERSION_NO/FILENAME

https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/names/NAME/versions/VERSION_NO/FILENAME'

Raw Package uploaded with a package name

https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/names/NAME/files/FILENAME

https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/names/NAME/files/FILENAME

Raw Package uploaded without a package name or version number

https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/files/FILENAME

https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/files/FILENAME

Some example curl commands to download a raw package from a private repository:

A package with no package name or version specified at upload using HTTP basic authentication:

curl -1sLf -u "USERNAME:PASSWORD" -O 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/files/FILENAME'

A specific version of a package using Entitlement Token authentication:

curl -1sLf -O 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/versions/VERSION_NO/FILENAME'

HTML / JSON Indexes

Cloudsmith supports serving Apache-style HTML and JSON formatted indexes of raw package files in the repository. You can enable index generation in the Repository Settings.

When enabled, the HTML index is available at:

Public Repositories

https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/

Private Repositories

https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/

https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/

The JSON index is available at:

Public Repositories

https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/index.json

Private Repositories

https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/raw/index.json

https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/raw/index.json

Upstream Proxying / Caching

Not Supported

Key Signing Support

GPG

Viewing Package Signatures

Package signatures for raw files are presented in three ways:

• As a separate entry in the HTML index.
• As an object keyed by signature on each file entry with the JSON index.
• Directly, by appending .asc to a file URL.

HTML Index

HTML Indexes will output a separate <li> entry containing the URL for the signature for each file. Additionally, the checksum is available under the data-checksum-sha256 attribute on the element:

JSON Index

JSON indexes will attach the package signature URL and checksum values under the checksum key for each package object:

{
   "packages" : [
      {
         "name" : "PACKAGE_NAME",
         "signature" : {
            "checksum_sha256" : "SIGNATURE_CHECKSUM",
            "url" : "https://dl.cloudsmith.io/TOKEN/OWNER/REPO/PACKAGE_IDENTIFIER/gpg.FILE_IDENTIFIER.asc"
         },
         ...
      }
   ]
}

File URL

For convenience, each of the file URLs listed above in 'Download a Package' can also map to the signature, by appending .asc to the URL. For example:

FILENAME="foo.zip"

# Retreive a file
curl -1sLf -O https://dl.cloudsmith.io/TOKEN/OWNER/REPO/raw/files/$FILENAME

# Retreive the signature for the file
curl -1sLf -O https://dl.cloudsmith.io/TOKEN/OWNER/REPO/raw/files/$FILENAME.asc

Troubleshooting

Please see the Troubleshooting page for further help and information.