Skip to content

Document platform coverage in the adopter tutorials: amd64-only images, Intel macOS installer dead end #219

Description

@jeremi

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

  • Both tutorials and the install docs state the platform reality; docs checks pass.

Security note

If this work surfaces a suspected vulnerability, report it per SECURITY.md; do not post details on this issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyReady for an implementation agent.area:docsDocumentation site ownership.area:registryctlregistryctl ownership.criticality:p2Priority/criticality P2.documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions