← Back to issue list

Docs: Tutorials assume an `amd64` host which causes `platforms:` and `.rock` filenames break for `arm64` readers

View original Github issue

Metadata

Project
rockcraft
Number
#1280
Type
issue
State
open
Author
minulo
Labels
—
Created
Updated
Closed
—

Current evaluation

Docs bug: hello-world, pyfiglet and Node.js tutorials hardcode `amd64` in `.rock` filenames/skopeo commands, breaking copy-paste on arm64 hosts. Maintainer assigned; fix in open PR #1289, not yet merged.

Suggested action: keep open

Reason: Confirmed still unfixed at HEAD: `docs/tutorial/code/hello-world/task.yaml` line 30 and `docs/tutorial/code/pyfiglet/task.yaml` line 22 still use `oci-archive:hello_latest_amd64.rock` / `pyfiglet_1.0.4_amd64.rock`, while the already-migrated Flask/Django/Go/FastAPI tutorials use `$(dpkg --print-architecture)`. The issue is triaged — asanvaq replied "I will assign this issue to you" and pointed at the Flask tutorial as the reference pattern — and the author volunteered a PR covering Hello World, Pack a Python package and Node.js, with the Chisel tutorial excluded because #1222 removed it. PR #1289 is still open/approved-not-merged, so the underlying docs bug persists and the issue should stay open until that lands.

Evaluated by: mr-cal-bot

Impact: 38 Quick Win: 23 Complexity: 28 Confidence: 86 Actionability: 85

Issue body

### Check existing issues - [x] I've verified that this request isn't described by any existing issues. ### Request ## Summary Several Rockcraft tutorials hardcode `amd64` in the `rockcraft.yaml` `platforms:` block and in the resulting `.rock` filenames used by later commands. A reader on an `arm64` host (e.g. Apple Silicon macOS, which is the majority of current Macs) packs a `..._arm64.rock` file, so the copy-paste `skopeo` import commands which reference `..._amd64.rock`, and this fails with a file-not-found error. ## Steps to reproduce ### Environment - Host architecture: `arm64` (Apple Silicon) - Build VM: Multipass (Ubuntu 24.04) - Docs version: `1.19` ### Reproduction: Using "Pack a Python package" as the clearest example: 1. In "Setup your environment," select the **macOS** tab (as an Apple Silicon user would). 2. Follow through to the `rockcraft.yaml` snippet: ```yaml platforms: arm64: ``` 3. Run `rockcraft pack` on the `arm64` host/VM. 4. Observe the produced file is `pyfiglet_0.7.6_arm64.rock`. 5. Run the import command exactly as written: ``` sudo rockcraft.skopeo --insecure-policy copy oci-archive:pyfiglet_0.7.6_amd64.rock docker-daemon:pyfiglet:0.7.6 ``` → fails, because the file on disk is `..._arm64.rock`. The Hello World and Chisel tutorials reproduce the same way with their respective filenames. ## Suggested fix Apply one consistent approach across the affected tutorials, changing from ``` sudo rockcraft.skopeo --insecure-policy copy oci-archive:hello_latest_amd64.rock docker-daemon:hello:latest ``` to something that use $(dpkg --print-architecture) like ``` sudo rockcraft.skopeo copy \ --insecure-policy \ oci-archive:hello_latest_$(dpkg --print-architecture).rock \ docker-daemon:hello:latest ``` ### Document location https://documentation.ubuntu.com/rockcraft/1.19/tutorial/hello-world/

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha
Impact: 38
Quick Win: 23
Complexity: 28
Confidence: 86
Actionability: 85
keep open Docs bug: hello-world, pyfiglet and Node.js tutorials hardcode `amd64` in `.rock` filenames/skopeo commands, breaking copy-paste on arm64 hosts. Maintainer assigned; fix in open PR #1289, not yet merged.
stealth/space-bunny-alpha
Impact: 37
Quick Win: 29
Complexity: 17
Confidence: 96
Actionability: 94
keep open Several tutorials hardcode amd64, breaking copy-pasted .rock imports on arm64. The contributor is preparing an architecture-agnostic fix in open PR #1289.
qwen3.6-35b-a3b-mtp-q6
Impact: 40
Quick Win: 34
Staleness: 15
Complexity: 15
Confidence: 85
Support Request: 0
keep open Documentation tutorials hardcode amd64 in platforms and .rock filenames, breaking for arm64 users. Issue assigned to contributor who is actively working on a fix.
qwen/qwen3.6-35b-a3b
Staleness: 10
Complexity: 15
Confidence: 90
Support Request: 5
keep open Documentation tutorials hardcode amd64 architectures in platforms blocks and rock filenames, causing failures for arm64 users. A maintainer has assigned the issue and the author is actively working on a PR to fix the affected tutorials.
qwen3.6-35b-a3b-mtp-q6
Staleness: 5
Complexity: 10
Confidence: 95
Support Request: 0
keep open Documentation issue where tutorials hardcode amd64 in platforms and filenames, breaking arm64 users. Author is actively working on a PR to fix this with maintainer guidance.
qwen3.6-35b-a3b-mtp-q6
Staleness: 5
Complexity: 15
Confidence: 90
Support Request: 10
needs triage Documentation tutorials hardcode amd64 architecture in platform definitions and rock filenames, causing copy-paste commands to fail for arm64 users. Author has offered to submit a fix.

Update history

No update history recorded yet.

Related work

  • Likely Fixed By: canonical/rockcraft#1289 (confidence 88%)

    Open PR "docs: make tutorials architecture-agnostic" (canonical/rockcraft#1289) applies the `$(dpkg --print-architecture)` pattern plus commented multi-arch `platforms:` blocks and post-pack notes to Hello World, pyfiglet and Node.js, explicitly fixing #1280.

  • Related To: canonical/rockcraft#1222 (confidence 70%)

    PR #1222 merged (cd5c9ca3) removed the "Shrink a rock with Chisel" tutorial, so that file listed in the issue no longer exists and is out of scope.

Related issues

No related issues found above the similarity threshold.