docs(eng-11208): Adds format & upstream documentation for Alpine and Wolfi

src/content/formats/alpine-repository.mdx

@@ -7,26 +7,40 @@ import { Tag, Note, Video } from '@/components';
 
 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.
 
-For more information on Alpine, please see:
+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](https://alpinelinux.org/): The official website for Alpine Linux
-- [Alpine Linux Wiki](https://wiki.alpinelinux.org): The official wiki for Alpine Linux
+- **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](https://alpinelinux.org/) — official Alpine Linux website
+- [Alpine Linux Wiki](https://wiki.alpinelinux.org) — Alpine Linux documentation
+- [Wolfi OS](https://wolfi.dev/) — 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](#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
 
 <Note variant="note" headline="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).
 </Note>
 
-In the following examples: 
+In the following examples:
 
 | Identifier      | Description                                                                                                                     |
 | :-------------- | :------------------------------------------------------------------------------------------------------------------------------ |
 | OWNER           | Your Cloudsmith account name or organization name (namespace)                                                                   |
 | REPOSITORY      | Your Cloudsmith Repository name (also called "slug")                                                                            |
-| VERSION         | Alpine distribution version, i.e. v3.8. You can also use "any-version" if your package is compatible with more than one version |
-| FINGERPRINT     | the 8 Byte fingerprint of the Public RSA key for the repository                                                                 |
-| TOKEN           | Your Cloudsmith Entitlement Token (see [Entitlements](/software-distribution/entitlement-tokens) for more details)                                       |
+| VERSION         | Alpine distribution version, e.g. `v3.23`. Use `any-version` if your package is compatible with more than one version           |
+| FINGERPRINT     | The 8-byte fingerprint of the public RSA key for the repository                                                                 |
+| TOKEN           | Your Cloudsmith Entitlement Token (see [Entitlements](/software-distribution/entitlement-tokens) 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                                                                                              |
@@ -37,42 +51,55 @@ In the following examples:
 
 For full details of how to install and setup the Cloudsmith CLI, see [Command Line Interface](/developer-tools/cli).
 
-The command to upload an Alpine package via the Cloudsmith CLI is: 
+#### Alpine Linux - Package Upload
+
+The command to upload an Alpine package via the Cloudsmith CLI is:
 
 ```shell
 cloudsmith push alpine OWNER/REPOSITORY/alpine/VERSION PACKAGE_NAME-PACKAGE_VERSION.apk
 ```
 
-Example: Upload a package for Alpine v3.8
+Upload a package for specific Alpine version:
 
 ```shell
-cloudsmith push alpine org/repo/alpine/v3.8 libjq-1.0.3.apk
+cloudsmith push alpine OWNER/REPOSITORY/alpine/v3.23 libjq-1.0.3.apk
 ```
 
-Example: Upload a package for any version of Alpine
+Upload a package for any version of Alpine:
 
 ```shell
-cloudsmith push alpine org/repo/alpine/any-version libjq-1.0.3.apk
+cloudsmith push alpine OWNER/REPOSITORY/alpine/any-version libjq-1.0.3.apk
 ```
 
+Upload a package for Wolfi:
+
+```shell
+cloudsmith push alpine OWNER/REPOSITORY/wolfi/any-version libjq-1.0.3.apk
+```
+
+<Note variant="note" headline="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.
+</Note>
+
 ### Upload via Cloudsmith Website
 
 Please see [Upload a Package](/artifact-management/package-upload) for details of how to upload via the Cloudsmith web app.
 
 ## Download / Install a Package
 
-You have a choice of 3 methods to setup your Cloudsmith repository: 
+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 quickly set up the repository automatically:
+To install Alpine packages from a public Cloudsmith repository, you can set up the repository using the following:
 
 ```shell
 sudo apk add --no-cache bash
+
 curl -sLf \
   'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/cfg/setup/bash.alpine.sh' \
   | sudo bash
@@ -82,104 +109,107 @@ If you need to force a specific distribution:
 
 ```shell
 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
+Or, you can manually configure the repository:
 
 ```shell
 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
 
 <Note variant="note" headline="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.
+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.
 </Note>
 
-<Note variant="warning" headline="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.
+<Note variant="warning" headline="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.
 </Note>
-To install Alpine packages from a private Cloudsmith repository, you can quickly set up the repository automatically:
+
+To install Alpine packages from a private Cloudsmith repository, you can set up the repository using the following:
 
 ```shell Entitlement Token Auth
 curl -sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/cfg/setup/bash.alpine.sh' \
 | sudo bash
 ```
-```shell HTTP Basic Auth (User & Pass)
-sudo apk add --no-cache bash
-curl -u "USERNAME:PASSWORD" -sLf \
-  'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/bash.alpine.sh' \
-  | sudo bash
-```
+
 ```shell HTTP Basic Auth (API-Key)
 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
 ```
+
 ```shell HTTP Basic Auth (Token)
 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:
+If you need to force a specific distribution, set `distro` and `codename` (for Alpine):
 
-```shell Entitlement Token Auth
+```shell Alpine (Entitlement Token)
 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
-```
-```shell HTTP Basic Auth (User & Pass)
-sudo apk add --no-cache bash
-curl -u "USERNAME:PASSWORD" -sLf \
-  'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/bash.alpine.sh' \
-  | sudo distro=alpine codename=VERSION bash
-```
-```shell HTTP Basic Auth (API-Key)
-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 distro=alpine codename=VERSION bash
-```
-```shell HTTP Basic Auth (Token)
-sudo apk add --no-cache bash
-curl -u "token:TOKEN" -sLf \
-  'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/bash.alpine.sh' \
   | sudo distro=alpine codename=VERSION bash
 ```
 
-Or, you can manually configure the repository:
+Or, you can manually configure the repository for Alpine:
 
 ```shell Entitlement Token Auth
-curl -sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/cfg/rsa/rsa.FINGERPRINT.key' > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
-curl -sLf 'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/cfg/setup/config.alpine.txt?distro=alpine&codename=VERSION' >> /etc/apk/repositories
+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
 ```
-```shell HTTP Basic Auth (User & Pass)
-curl -u "USERNAME:PASSWORD" -sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/rsa/rsa.FINGERPRINT.key' > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
-curl -u "USERNAME:PASSWORD" -sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/config.alpine.txt?distro=alpine&codename=VERSION' >> /etc/apk/repositories
-apk update
-```
-```shell HTTP Basic Auth (API-Key)
-curl -u "USERNAME:API-KEY" -sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/rsa/rsa.FINGERPRINT.key' > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
-curl -u "USERNAME:API-KEY" -sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/config.alpine.txt?distro=alpine&codename=VERSION' >> /etc/apk/repositories
+
+```shell HTTP Basic Auth
+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
 ```
-```shell HTTP Basic Auth (Token)
-curl -u "token:TOKEN" -sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/rsa/rsa.FINGERPRINT.key' > /etc/apk/keys/REPOSITORY@OWNER-FINGERPRINT.rsa.pub
-curl -u "token:TOKEN" -sLf 'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/cfg/setup/config.alpine.txt?distro=alpine&codename=VERSION' >> /etc/apk/repositories
-apk update
+
+Alternatively, for Wolfi distributions:
+
+```shell Manual Configuration
+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
 ```
-### Installing a package
 
-After you have set up the repository, to install a package you do: 
+<Note variant="note" headline="No automated setup script for Wolfi">
+The automated setup script (`bash.alpine.sh`) does not support Wolfi. Use the manual setup for this distribution.
+</Note>
+
+
+### Installing a Package
+
+After setting up the repository, install a package with:
 
 ```shell
 sudo apk add PACKAGE_NAME=PACKAGE_VERSION --update-cache
@@ -193,7 +223,7 @@ If you no longer want to install packages from your Cloudsmith repository, you c
 $EDITOR /etc/apk/repositories
 ```
 
-Remove the `/alpine/VERSION/main` line, save then execute:
+Remove the cloudsmith repository line, save then execute:
 
 ```shell
 rm -f /etc/apk/keys/REPOSITORY@cloudsmith-FINGERPRINT.rsa.pub
@@ -202,7 +232,26 @@ apk update
 
 ## Upstream Proxying / Caching
 
-<Tag variant="dark-grey" theme="legacy">Not Supported</Tag>
+<Tag variant="dark-green" theme="legacy">Supported</Tag>
+
+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
+
+| Distribution | Upstream URL                             | Notes                      |
+|:-------------|:-----------------------------------------|:---------------------------|
+| Alpine Linux | `https://dl-cdn.alpinelinux.org/alpine/` | Official Alpine CDN mirror |
+| Wolfi        | `https://packages.wolfi.dev/os/`         | Official Wolfi OS packages |
+
+
+### Configure an Upstream
+
+Please see our [Upstream Proxying](/repositories/upstreams#create-a-alpine-upstream) documentation for further instructions on form fields and configuration options.
 
 ## Key Signing Support