Supported Formats

Alpine Repository

Alpine Linux is a lightweight Linux Distribution that is designed to be smaller and more resource efficient, and as such has grown popular as the basis for Docker containers.

Cloudsmith supports hosting and distributing packages in the APK format, used by both Alpine Linux and Wolfi. Although both distributions use the same package format, they are distinct and incompatible — packages built for Alpine Linux cannot be used on Wolfi, and vice versa.

• Alpine Linux is a lightweight Linux distribution popular as a Docker container base image. It uses versioned releases (e.g., v3.0, …, v3.22, v3.23, etc.) grouped by architecture e.g. v3.23/main/aarch64/ via the apk package manager.
• Wolfi is a minimal, container-optimized Linux distribution from Chainguard. Unlike Alpine, it follows a rolling release model in which packages are removed after 12 months.

For more information:

• Alpine Linux — official Alpine Linux website
• Alpine Linux Wiki — Alpine Linux documentation
• Wolfi OS — official Wolfi website

What Cloudsmith Supports

Cloudsmith repositories for the Alpine format support:

• Public and private package hosting serve APK packages to authenticated users or publicly
• RSA signing all repositories are signed with an RSA key that clients can verify via apk. Alpine uses SHA-1 and Wolfi uses SHA-256.
• Upstream proxying and caching proxy and cache packages from Alpine Linux mirrors, Wolfi, or Chainguard (see Upstream Proxying / Caching)
• Both Alpine Linux and Wolfi a single repository format handles both distributions; the distribution is selected at upload time and automatically detected at install time

Contextual Documentation

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

In the following examples:

Upload a Package

Upload via the Cloudsmith CLI

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

Alpine Linux - Package Upload

The command to upload an Alpine package via the Cloudsmith CLI is:

cloudsmith push alpine OWNER/REPOSITORY/alpine/VERSION PACKAGE_NAME-PACKAGE_VERSION.apk

Upload a package for specific Alpine version:

cloudsmith push alpine OWNER/REPOSITORY/alpine/v3.23 libjq-1.0.3.apk

Upload a package for any version of Alpine:

cloudsmith push alpine OWNER/REPOSITORY/alpine/any-version libjq-1.0.3.apk

Upload a package for Wolfi:

cloudsmith push alpine OWNER/REPOSITORY/wolfi/any-version libjq-1.0.3.apk

Contextual Documentation

Wolfi has a single index that typically contains all versions available within the past 12 months. When uploading a Wolfi package to Cloudsmith, use the wolfi/any-version distribution.

Upload via Cloudsmith Website

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

Download / Install a Package

You have a choice of 3 methods to set up 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 Alpine packages from a public Cloudsmith repository, you can set up the repository using the following:

sudo apk add --no-cache bash

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

If you need to force a specific distribution:

sudo apk add --no-cache bash

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

Or, you can manually configure the repository:

curl -sLf 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/rsa/rsa.FINGERPRINT.key' > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
curl -sLf 'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/setup/config.alpine.txt?distro=alpine&codename=VERSION' >> /etc/apk/repositories
apk update

Private Repositories

Private Repositories

Private Cloudsmith repositories require authentication. You can choose between Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Secrets management

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

To install Alpine packages from a private Cloudsmith repository, you can set up the repository using the following:

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

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

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

If you need to force a specific distribution, set distro and codename (for Alpine):

sudo apk add --no-cache bash
curl -sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/cfg/setup/bash.alpine.sh' \
  | sudo distro=alpine codename=VERSION bash

Or, you can manually configure the repository for Alpine:

curl -1sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/rsa.FINGERPRINT.key' \
  > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
echo "https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/alpine/VERSION/main" \
  > /etc/apk/repositories
apk update

curl -u "token:TOKEN" -1sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/rsa.FINGERPRINT.key' \
  > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
echo "https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/alpine/VERSION/main" \
  > /etc/apk/repositories
apk update

Alternatively, for Wolfi distributions:

apk add curl

# Remove existing Wolfi/Chainguard keys and repository list
rm -f /etc/apk/keys/chainguard-*
rm -f /etc/apk/keys/wolfi-signing.rsa.pub
rm -f /etc/apk/repositories

# Download the Cloudsmith RSA key
curl -L -o /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub \
  'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/rsa.FINGERPRINT.key'

# Configure the repository
echo "https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/alpine/os" \
  > /etc/apk/repositories

apk update -v --no-cache
apk add -v --no-cache PACKAGE_NAME

No automated setup script for Wolfi

The automated setup script (bash.alpine.sh) does not support Wolfi. Use the manual setup for this distribution.

Installing a Package

After setting up the repository, install a package with:

sudo apk add PACKAGE_NAME=PACKAGE_VERSION --update-cache

Removing Setup

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

$EDITOR /etc/apk/repositories

Remove the cloudsmith repository line, save then execute:

rm -f /etc/apk/keys/REPOSITORY@cloudsmith-FINGERPRINT.rsa.pub
apk update

Upstream Proxying / Caching

The Alpine format supports upstream proxying and caching for both Alpine Linux and Wolfi repositories. When a package is requested, Cloudsmith checks for a local copy. If missing, it fetches the package from the upstream, caches it as a first-class local package, and serves it.

The key difference between Alpine and Wolfi upstreams is in their URL structures — these paths only return packages for the given distribution:

• Alpine Linux uses a versioned path structure: /{version}/{branch}/{arch}/ (e.g., /v3.23/main/x86_64/)
• Wolfi uses a flat structure with no version hierarchy: /{arch}/ (e.g., /x86_64/)

Supported Upstream Sources

Configure an Upstream

Please see our Upstream Proxying documentation for further instructions on form fields and configuration options.

Key Signing Support

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated last week