From 0f53b0fa26b60fe1de1f620764ffc85ffd517c47 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Thu, 4 Jun 2026 13:57:36 -0700
Subject: [PATCH 1/3] Publish Docker Hub overview on each release.

---
 .github/workflows/publish.yml | 34 ++++++++++++
 README.md                     |  1 +
 docker/README.md              | 99 +++++++++++++++++++++++++++++++++++
 3 files changed, 134 insertions(+)
 create mode 100644 docker/README.md

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 46cb2b3..2e93cb2 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -223,6 +223,39 @@ jobs:
             --stellar-cli-version "$STELLAR_CLI_VERSION" \
             --registry "$REGISTRY"
 
+  description:
+    name: update Docker Hub description
+    needs: [manifest]
+    # Skip for forks publishing to a non-Docker-Hub registry; the Docker Hub
+    # API only makes sense for docker.io repositories.
+    if: startsWith(vars.REGISTRY || 'docker.io/stellar/stellar-cli', 'docker.io/')
+    runs-on: ubuntu-24.04
+    steps:
+      - name: checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: update full description from docker/README.md
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+        run: |
+          # Derive the Docker Hub "namespace/repo" path from REGISTRY by
+          # dropping the docker.io/ host prefix.
+          repo="${REGISTRY#docker.io/}"
+
+          token=$(jq -n --arg u "$DOCKERHUB_USERNAME" --arg p "$DOCKERHUB_TOKEN" \
+            '{username: $u, password: $p}' | \
+            curl -sf -X POST "https://hub.docker.com/v2/users/login/" \
+              -H "Content-Type: application/json" \
+              -d @- \
+            | jq -r .token)
+
+          jq -n --arg desc "$(cat ./docker/README.md)" '{"full_description": $desc}' | \
+            curl -sf -X PATCH "https://hub.docker.com/v2/repositories/${repo}/" \
+              -H "Content-Type: application/json" \
+              -H "Authorization: Bearer ${token}" \
+              -d @- \
+            > /dev/null
+
   release:
     name: enrich github release with sbom and provenance
     needs: [matrix, aliases]
@@ -267,6 +300,7 @@ jobs:
       - build
       - manifest
       - aliases
+      - description
       - release
     runs-on: ubuntu-24.04
     steps:
diff --git a/README.md b/README.md
index 2203347..b29c5b4 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,7 @@ compare the resulting WASM sha256.
 | `Dockerfile`               | Two-stage builder + runtime, args-driven.                                                                                                                                                                                            |
 | `builds.json`              | Source of truth for which (stellar-cli, rust base key) pairs we publish.                                                                                                                                                             |
 | `builds.schema.json`       | JSON Schema for `builds.json`.                                                                                                                                                                                                       |
+| `docker/README.md`         | Docker Hub overview. The publish workflow pushes this to the repository's `full_description` on each release.                                                                                                                       |
 | `scripts/build_image.py`   | Local single-image build.                                                                                                                                                                                                            |
 | `scripts/validate_json.py` | Validates every `*.json` for sorted keys and `builds.json` against the schema.                                                                                                                                                       |
 | `scripts/refresh.py`       | For one `--stellar-cli-version`: picks the rust base labels, resolves the upstream cli ref and each base's index digest, and appends the fully-qualified pins `<label>@<digest>` (append-only; already-published pins are retained). |
diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 0000000..9126e43
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,99 @@
+# Stellar CLI
+
+Docker images for the [Stellar CLI](https://github.com/stellar/stellar-cli).
+
+Also compatible as a
+[SEP-58](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0058.md)
+image for reproducible Stellar contract builds.
+
+Each image:
+
+- Pins its base via the official `rust:<version>-<suffix>` multi-arch index
+  digest.
+- Pins the Rust toolchain via `RUSTUP_TOOLCHAIN`, baked in so an in-source
+  `rust-toolchain.toml` cannot silently swap it.
+- Pins `stellar-cli` to a specific upstream commit, installed with
+  `cargo install --locked`.
+- Ships with the `wasm32v1-none` target preinstalled.
+- Sets `WORKDIR /source` and `ENTRYPOINT ["stellar"]`.
+
+## Quick start
+
+Pull a published image (per-host arch):
+
+```sh
+docker run --rm docker.io/stellar/stellar-cli:latest --version
+```
+
+Confirm the rustc version used:
+
+```sh
+docker run --rm --entrypoint rustc docker.io/stellar/stellar-cli:latest --version
+```
+
+Build a contract by mounting the contract directory at `/source`:
+
+```sh
+docker run --rm -v "$PWD:/source" docker.io/stellar/stellar-cli:latest contract build --locked
+```
+
+The image exposes four well-known paths:
+
+| Path       | What                                                                              |
+| ---------- | --------------------------------------------------------------------------------- |
+| `/source`  | `WORKDIR`. Bind-mount your contract here.                                         |
+| `/config`  | `STELLAR_CONFIG_HOME`. Mount to persist network and identity configuration.       |
+| `/data`    | `STELLAR_DATA_HOME`. Mount to persist CLI data.                                   |
+| `/stellar` | Home for user `stellar` (UID 1000). Mount to persist the cargo cache (see below). |
+
+The image runs as user `stellar` (UID 1000) with `/stellar` as the home
+directory. `CARGO_HOME` resolves to `/stellar/.cargo` inside the container,
+which is wiped on exit by default.
+
+To reuse cargo's registry index, git checkouts, and crate sources across runs —
+and to make the image work under `--user "$(id -u):$(id -g)"` on Linux hosts
+whose UID is not 1000 — mount a writable host directory at `/stellar`:
+
+```sh
+mkdir -p /tmp/myproject
+docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  -v /tmp/myproject:/stellar \
+  -v "$PWD:/source" \
+  docker.io/stellar/stellar-cli:latest contract build --locked
+```
+
+## Verifiable builds ([SEP-58](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0058.md))
+
+For verifiable references, **always pin to a per-arch single-architecture digest
+(`@sha256:…`)** — it is the only stable reference. Never use a tag or a
+multi-arch manifest list digest in `bldimg`:
+
+```sh
+# Find the per-arch digest for the architecture you used to build.
+# Pick any of the manifest-list tags from the release notes,
+# e.g. :26.0.0-rust1.94.0-slim-trixie, or the :26.0.0 alias:
+docker buildx imagetools inspect docker.io/stellar/stellar-cli:26.0.0
+```
+
+Record the per-arch digest in your contract's `bldimg` metadata. A verifier will
+pull the same per-arch image, run the same `docker run` invocation, and compare
+the resulting WASM sha256.
+
+## Image Tags
+
+- `latest` — most recent release.
+- `X.Y.Z` — specific release version (e.g. `26.1.0`).
+- `<X.Y.Z>-rust<rust image>` — multi-arch manifest list (e.g.
+  `26.1.0-rust1.95.0-slim-trixie`).
+- `<X.Y.Z>-rust<rust image>-<arch>` — per-arch release (e.g.
+  `26.1.0-rust1.95.0-slim-trixie-arm64`).
+
+## Source
+
+Built from
+[stellar/stellar-cli-docker](https://github.com/stellar/stellar-cli-docker).
+
+## License
+
+[Apache-2.0](https://github.com/stellar/stellar-cli-docker/blob/main/LICENSE).

From ed2db79e4049204dacb38f6cbb7d4cac78212ec8 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Mon, 8 Jun 2026 14:32:53 -0700
Subject: [PATCH 2/3] Surface Docker Hub API errors in publish workflow.

---
 .github/workflows/publish.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 2e93cb2..5996a76 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -244,13 +244,13 @@ jobs:
 
           token=$(jq -n --arg u "$DOCKERHUB_USERNAME" --arg p "$DOCKERHUB_TOKEN" \
             '{username: $u, password: $p}' | \
-            curl -sf -X POST "https://hub.docker.com/v2/users/login/" \
+            curl -sSf -X POST "https://hub.docker.com/v2/users/login/" \
               -H "Content-Type: application/json" \
               -d @- \
-            | jq -r .token)
+            | jq -er .token)
 
           jq -n --arg desc "$(cat ./docker/README.md)" '{"full_description": $desc}' | \
-            curl -sf -X PATCH "https://hub.docker.com/v2/repositories/${repo}/" \
+            curl -sSf -X PATCH "https://hub.docker.com/v2/repositories/${repo}/" \
               -H "Content-Type: application/json" \
               -H "Authorization: Bearer ${token}" \
               -d @- \

From 6b07240fede617e0b2349a6e104375f0bd3d31a0 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Tue, 9 Jun 2026 10:04:00 -0700
Subject: [PATCH 3/3] Clarify how to find the per-arch image digest.

---
 docker/README.md | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index 9126e43..b34a078 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -19,7 +19,7 @@ Each image:
 
 ## Quick start
 
-Pull a published image (per-host arch):
+Pull a published image:
 
 ```sh
 docker run --rm docker.io/stellar/stellar-cli:latest --version
@@ -70,15 +70,24 @@ For verifiable references, **always pin to a per-arch single-architecture digest
 multi-arch manifest list digest in `bldimg`:
 
 ```sh
-# Find the per-arch digest for the architecture you used to build.
-# Pick any of the manifest-list tags from the release notes,
-# e.g. :26.0.0-rust1.94.0-slim-trixie, or the :26.0.0 alias:
-docker buildx imagetools inspect docker.io/stellar/stellar-cli:26.0.0
+# List the per-arch digest for each platform behind a tag. Pick any of the
+# manifest-list tags from the release notes, e.g. :26.0.0-rust1.94.0-slim-trixie,
+# or the :26.0.0 alias:
+docker buildx imagetools inspect docker.io/stellar/stellar-cli:26.0.0 \
+  --format '{{range .Manifest.Manifests}}{{if and .Platform (ne .Platform.OS "unknown")}}{{.Platform.OS}}/{{.Platform.Architecture}} {{.Digest}}{{println}}{{end}}{{end}}'
 ```
 
-Record the per-arch digest in your contract's `bldimg` metadata. A verifier will
-pull the same per-arch image, run the same `docker run` invocation, and compare
-the resulting WASM sha256.
+This prints one line per architecture, e.g.:
+
+```
+linux/amd64 sha256:…
+linux/arm64 sha256:…
+```
+
+Record the `sha256:…` digest for the architecture you built on in your
+contract's `bldimg` metadata — not the tag and not the manifest-list digest. A
+verifier will pull that same per-arch image, run the same `docker run`
+invocation, and compare the resulting WASM sha256.
 
 ## Image Tags