Part of the 1.0 release-readiness push (see release/READINESS.md, section 1).
Context
- Product images are built
--platform linux/amd64 only (.github/workflows/release.yml), no multi-arch manifest. The only place this is explained to readers is tutorials/verify-opencrvs-claims.mdx (~lines 117-122). The two primary adopter tutorials (publish-spreadsheet-secured-registry-api, verify-claim-registry-api) never mention it, including their troubleshooting tables. registryctl does auto-inject DOCKER_DEFAULT_PLATFORM=linux/amd64 on arm64 hosts (compose_platform_override, crates/registryctl/src/lib.rs ~line 3259), which usually saves the day silently, but when detection misses, the reader gets a raw Docker manifest error with no documented explanation.
crates/registryctl/install.sh maps x86_64 macOS to the asset name registryctl-<tag>-macos-amd64, which is never published (release assets: linux-amd64, linux-arm64, macos-arm64). The script falls back to cargo install --git, meaning an Intel Mac evaluator's very first command requires installing a Rust toolchain, with no advance warning in the docs.
Scope
- Troubleshooting rows in both primary tutorials for the image-platform case (symptom: Docker "no linux/arm64 manifest" error; fix:
DOCKER_DEFAULT_PLATFORM=linux/amd64).
- A supported-platforms note where install.sh is introduced, stating Intel macOS falls back to a source build.
- Building multi-arch images or a macos-amd64 binary would resolve this properly; if that is preferred, record the decision and scope it separately.
Acceptance
Security note
If this work surfaces a suspected vulnerability, report it per SECURITY.md; do not post details on this issue.
Part of the 1.0 release-readiness push (see
release/READINESS.md, section 1).Context
--platform linux/amd64only (.github/workflows/release.yml), no multi-arch manifest. The only place this is explained to readers istutorials/verify-opencrvs-claims.mdx(~lines 117-122). The two primary adopter tutorials (publish-spreadsheet-secured-registry-api,verify-claim-registry-api) never mention it, including their troubleshooting tables. registryctl does auto-injectDOCKER_DEFAULT_PLATFORM=linux/amd64on arm64 hosts (compose_platform_override,crates/registryctl/src/lib.rs~line 3259), which usually saves the day silently, but when detection misses, the reader gets a raw Docker manifest error with no documented explanation.crates/registryctl/install.shmapsx86_64macOS to the asset nameregistryctl-<tag>-macos-amd64, which is never published (release assets: linux-amd64, linux-arm64, macos-arm64). The script falls back tocargo install --git, meaning an Intel Mac evaluator's very first command requires installing a Rust toolchain, with no advance warning in the docs.Scope
DOCKER_DEFAULT_PLATFORM=linux/amd64).Acceptance
Security note
If this work surfaces a suspected vulnerability, report it per
SECURITY.md; do not post details on this issue.