Debian Repository

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 n' paste snippets (with your namespace/repo pre-configured).

In the following examples:

Identifier	Description
OWNER	Your Cloudsmith account name or organization name (namespace)
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.

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:

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:

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

Example: Upload a binary package for Ubuntu Xenial

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

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)

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

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

Source Packages

A source package is one that provides you with all of the necessary files to compile or otherwise, build the desired piece of software. In other words, you can get the sources used to create a binary package, and compile them yourself; perhaps to customise the package, or build it for a different operating environment.

When uploading a DSC package, the following files are involved:

The DSC package file is a metadata file that describes the other sources/changes files. (Required)
The sources file contains the actual source files used to build the software. (Required)
The changes file usually contains the patch applied, or to be applied, to the sources file if different from the original. (Optional)

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

cloudsmith push deb OWNER/REPOSITORY/DISTRO/VERSION PACKAGE_NAME-PACKAGE_VERSION.PACKAGE_ARCH.dsc --sources-file SOURCES_FILENAME

Example: Upload a source package for Ubuntu Xenial

cloudsmith push deb org/repo/ubuntu/xenial mypackage-1.1.2-2.x86_64.src --sources-file mypackage-1.1.2-2.x86_64.tar.xz

Example: Upload a source package for any version of Ubuntu

cloudsmith push deb org/repo/ubuntu/any-version mypackage-1.1.2-2.x86_64.src --sources-file mypackage-1.1.2-2.x86_64.tar.xz

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

cloudsmith push deb org/repo/any-distro/any-version mypackage-1.1.2-2.x86_64.src --sources-file mypackage-1.1.2-2.x86_64.tar.xz

Automatically detecting changes and sources archives for upload

The script below will loop over all .dsc files in $WORKING_DIR and parse it to identify the source and changes files to be passed to the --source-file and --changes-file CLI options.

This relies on the dcmd tool being installed and the .dsc file and the associated changes and source archives being present in $WORKING_DIR.

for DESCRIPTION_FILE in ${WORKING_DIR}/*.dsc; do
  cloudsmith push deb ${REPO}/any-distro/any-version "$DESCRIPTION_FILE" --source-file=$(dcmd --orig "$DESCRIPTION_FILE") --changes-file=$(dcmd --debtar "$DESCRIPTION_FILE")
done

Upload via Cloudsmith Website

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

Download / Install a Package

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

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

If you need to force a specific distribution:

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

Or, you can manually configure the repository

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/OWNER-REPOSITORY-archive-keyring.gpg

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

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

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

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.

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

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

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

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

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

If you need to force a specific distribution:

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

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

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

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

Or, you can manually configure the repository:

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 -1sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -1sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/OWNER-REPOSITORY.list
apt-get update

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" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -u "USERNAME:PASSWORD" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/OWNER-REPOSITORY.list
apt-get update

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" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -u "USERNAME:API-KEY" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/OWNER-REPOSITORY.list
apt-get update

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" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/gpg/gpg.FINGERPRINT.key'  | apt-key add -
curl -u "token:TOKEN" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/config.deb.txt?distro=DISTRO&codename=VERSION'> /etc/apt/sources.list.d/OWNER-REPOSITORY.list
apt-get update

Installing a package

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

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:

rm /etc/apt/sources.list.d/OWNER-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.

Upload a Package

Upload via the Cloudsmith CLI

Binary Packages

Source Packages

Automatically detecting changes and sources archives for upload

Upload via Cloudsmith Website

Download / Install a Package

📘

Setup

Public Repositories

Private Repositories

📘

🚧

Installing a package

Removing Setup

Upstream Proxying / Caching

Key Signing Support

Troubleshooting

Cloudsmith is the new standard in Package / Artifact Management and Software Distribution