Publish Docker Hub overview on each release

.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 -sSf -X POST "https://hub.docker.com/v2/users/login/" \
+              -H "Content-Type: application/json" \
+              -d @- \
+            | jq -er .token)
+
+          jq -n --arg desc "$(cat ./docker/README.md)" '{"full_description": $desc}' | \
+            curl -sSf -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:

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

docker/README.md

@@ -0,0 +1,108 @@
+# 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:
+
+```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
+# 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}}'
+```
+
+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
+
+- `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).