Raw Repository

Cloudsmith provides public & private repositories for Raw files

834834

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).

In the following examples:

Identifier

Description

OWNER

Your Cloudsmith account name or organisation name (namespace)

REPOSITORY

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

FILENAME

The name of your file (i.e file.zip or file.txt etc)

VERSION_NO

The optional version number for a package

NAME

The optional package name

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:

12071207

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.

11851185

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:

11551155

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 -O 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/raw/files/FILENAME'

A specific version of a package

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

The latest version of the package

curl -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 -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 -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:

542542

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 https://dl.cloudsmith.io/TOKEN/OWNER/REPO/raw/files/$FILENAME

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

Troubleshooting

Please see the Troubleshooting page for further help and information.


Did this page help you?