Supported formats

Debian repository

Cloudsmith provides public & private repositories for Debian packages.

For more information on Debian, please see:

Debian: The official website for Debian
Debian Packages Documentation: The official docs for Debian Packages

Contextual Documentation
The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets that have your workspace, repository, and RSA key pre-configured.

In the following examples:

Identifier	Description
WORKSPACE	Your Cloudsmith workspace slug
REPOSITORY	Your Cloudsmith Repository name (also called "slug")
DISTRO	Your distribution (i.e debian, ubuntu). You can also use "any-distro" if your package is compatible with more than more distribution
VERSION	Your version name (i.e xenial, buster). You can also use "any-version" if your package is compatible with more than more version
FINGERPRINT	The 8 Byte fingerprint of the Public GPG key for the repository
TOKEN	Your Cloudsmith Entitlement Token (see Entitlements for more details)
USERNAME	Your Cloudsmith username
PASSWORD	Your Cloudsmith password
API-KEY	Your Cloudsmith API Key
PACKAGE_NAME	The name of your package
PACKAGE_VERSION	The version number of your package
PACKAGE_ARCH	The architecture of your package (e.g. `x86_64`)
PACKAGE_COMPONENT	The release component (channel) of your package (e.g. `unstable`)
SOURCES_FILENAME	The filename of the Debian sources, for a Debian source (`.dsc`) package.
DSC_FILENAME	The filename of the Debian source control (`.dsc`) file.

Upload a package

You can upload either source packages (.dsc) or binary packages (.deb)

To upload a binary package, you will need to generate your package first. We highly recommend fpm for simplifying this. With fpm, you can build a package from a directory that represents the layout on the target system installation using:

shell

fpm -f -s dir -t deb -n PACKAGE_NAME -v PACKAGE_VERSION .

Upload via the Cloudsmith CLI

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

Binary packages

The command to upload a Debian binary package via the Cloudsmith CLI is:

shell

cloudsmith push deb WORKSPACE/REPOSITORY/DISTRO/VERSION PACKAGE_NAME-PACKAGE_VERSION.PACKAGE_ARCH.deb

Example: Upload a binary package for Ubuntu Xenial

shell

cloudsmith push deb org/repo/ubuntu/xenial libxml2-2.9.4-2.x86_64.deb

Example: Upload a binary package for any version of Ubuntu

shell

cloudsmith push deb org/repo/ubuntu/any-version libxml2-2.9.4-2.x86_64.deb

Example: Upload a binary package for any version of Ubuntu, within the unstable release component (channel)

shell

cloudsmith push deb org/repo/ubuntu/any-version libxml2-2.9.4-2.x86_64.deb --component unstable

Example: Upload a binary package for any version of any distribution

shell

cloudsmith push deb org/repo/any-distro/any-version libxml2-2.9.4-2.x86_64.deb

Source packages

A source package provides the files required to build a Debian binary package. A Debian source package contains:

A Debian source control (.dsc) file that describes the package and lists its members.
An upstream or native source archive.
A Debian packaging archive or diff for non-native packages.

Keep the .dsc file and every archive it references in the same directory. The CLI reads Checksums-Sha256 or Files from the .dsc file, identifies the required source package members, and uploads them together:

shell

cloudsmith push deb WORKSPACE/REPOSITORY/DISTRO/VERSION DSC_FILENAME

Example: Upload a source package for Ubuntu Xenial

shell

cloudsmith push deb org/repo/ubuntu/xenial libxml2_2.9.4-2.dsc

Example: Upload a source package for any version of any distribution

shell

cloudsmith push deb org/repo/any-distro/any-version libxml2_2.9.4-2.dsc

The CLI supports source formats 1.0, 2.0, 3.0 (native), and 3.0 (quilt). It also reads plain and OpenPGP-clearsigned .dsc files.

Use --dsc-file DSC_FILENAME to parse a .dsc file other than the final command argument.

To set a member yourself, use --sources-file SOURCES_FILENAME or --changes-file. An explicit option always takes precedence over the derived value for that member. Passing --sources-file on its own disables automatic parsing, so to override the source archive while still deriving the Debian packaging archive, pass --dsc-file as well.

Unsupported source package members
The CLI skips detached upstream signatures such as *.orig.tar.gz.asc with a warning, because the deb package format has no field for them. Cloudsmith does not support multi-component Debian source packages, so the CLI rejects a .dsc file that references *.orig-COMPONENT.tar.* members.

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Download / install a package

Recommended APT Version
We recommend using apt v1.2.0 or newer so that you are able to fetch repository indexes using acquire-by-hash. This will avoid race conditions when updating your repository whilst simultaneously deploying from it.

Setup

You have a choice of 3 methods to setup your Cloudsmith repository:

Automatic configuration (recommended)
Force a specific distribution/release (if your system is compatible but not identical)
Manual configuration

Public repositories

To install Debian packages from a public Cloudsmith repository, you can quickly set up the repository automatically:

shell

curl -sLf \
  'https://dl.cloudsmith.io/public/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo bash

If you need to force a specific distribution:

shell

curl -sLf \
  'https://dl.cloudsmith.io/public/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo distro=DISTRO codename=VERSION bash

Or, you can manually configure the repository

shell

apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https

# For Debian Stretch, Ubuntu 16.04 and later
keyring_location=/usr/share/keyrings/WORKSPACE-REPOSITORY-archive-keyring.gpg

# For Debian Jessie, Ubuntu 15.10 and earlier
keyring_location=/etc/apt/trusted.gpg.d/WORKSPACE-REPOSITORY.gpg

curl -sLf 'https://dl.cloudsmith.io/public/WORKSPACE/REPOSITORY/gpg.FINGERPRINT.key' |  gpg --dearmor > ${keyring_location}

curl -sLf 'https://dl.cloudsmith.io/public/WORKSPACE/REPOSITORY/config.deb.txt?distro=DISTRO&codename=VERSION' > /etc/apt/sources.list.d/WORKSPACE-REPOSITORY.list

Private repositories

Private Repositories
Private Cloudsmith repositories 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.

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

To install Debian packages from a private Cloudsmith repository, you can quickly set up the repository automatically:

shell

curl -sLf 'https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
| sudo bash

shell

sudo apk add --no-cache bash
curl -u "USERNAME:PASSWORD" -sLf \
  'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo bash

shell

sudo apk add --no-cache bash
curl -u "USERNAME:API-KEY" -sLf \
  'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo bash

shell

sudo apk add --no-cache bash
curl -u "token:TOKEN" -sLf \
  'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo bash

If you need to force a specific distribution:

shell

curl -sLf 'https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
| sudo distro=DISTRO codename=VERSION bash

shell

curl -u "USERNAME:PASSWORD" -sLf \
  'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo distro=DISTRO codename=VERSION bash

shell

curl -u "USERNAME:API-KEY" -sLf \
  'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo distro=DISTRO codename=VERSION bash

shell

curl -u "token:TOKEN" -sLf \
  'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/bash.deb.sh' \
  | sudo distro=DISTRO codename=VERSION bash

Or, you can manually configure the repository:

shell

apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https
curl -sLf 'https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -sLf 'https://dl.cloudsmith.io/TOKEN/WORKSPACE/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/WORKSPACE-REPOSITORY.list
apt-get update

shell

apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https
curl -u "USERNAME:PASSWORD" -sLf 'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -u "USERNAME:PASSWORD" -sLf 'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/WORKSPACE-REPOSITORY.list
apt-get update

shell

apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https
curl -u "USERNAME:API-KEY" -sLf 'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -u "USERNAME:API-KEY" -sLf 'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/WORKSPACE-REPOSITORY.list
apt-get update

shell

apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https
curl -u "token:TOKEN" -sLf 'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -u "token:TOKEN" -sLf 'https://dl.cloudsmith.io/basic/WORKSPACE/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/WORKSPACE-REPOSITORY.list
apt-get update

Installing a package

After you have set up the repository, to install a package you do:

shell

sudo apt-get install PACKAGE_NAME=PACKAGE_VERSION

Removing setup

If you no longer want to install packages from your Cloudsmith repository, you can remove it with:

shell

rm /etc/apt/sources.list.d/WORKSPACE-REPOSITORY.list
apt-get clean
rm -rf /var/lib/apt/lists/*
apt-get update

Upstream proxying / caching

Configurable Proxying Caching

You can configure upstream Debian repositories that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Please see our Upstream Proxying documentation for further instructions.

Key signing support

GPG Index

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated 6 days ago