Files
archy/docs/HANDOFF-2026-10-11-ARM64-M2-BUILD.md

7.1 KiB

Handoff — ARM64 build on the M2 (supersedes 2026-10-10 handoff where they differ)

Date: 2026-10-11 Goal: Build Archipelago for ARM (Raspberry Pi and other ARM devices) with an installer/image. Nothing bootable exists yet.

Repo state

  • Laptop ~/Projects/archy: sparse + partial clone (blob:none). Local main fast-forwarded to origin/main = 2d19d03e (v1.9.2-alpha changelog merge). Backend/frontend versions on main: 1.9.1-alpha.
  • Branch arm64-pi-test (from main 2d19d03e), commit 4cd6449b "build: enable aarch64 (Raspberry Pi) backend and bitcoin image builds". Contents = old stash@{0} applied cleanly (build-backend.sh, build-bitcoin-image.sh, bitcoin-core/knots Dockerfiles, docs/README.md, docs/raspberry-pi-test-install.md). Not pushed anywhere.
  • stash@{0} still exists on the laptop (safe to drop once the branch is pushed).
  • The laptop's working branch was app/angor-frpc (untouched). Untracked handoff/notes files on the laptop are intentionally uncommitted.
  • Same commit applied on the M2 as b158aac on branch arm64-pi-test (via git am, local identity passed with -c, global git config untouched).

The ARM build machine ("the M2")

  • ssh m2 (Host entry in the maintainer's laptop ~/.ssh/config; address/user not recorded in the repo)
    • It is Arch Linux ARM (aarch64, Asahi) — not macOS. 8 cores, 7.4 GB RAM + 7.4 GB zram swap, ~124 GB free.
    • Key ~/.ssh/id_ed25519_m2 (no passphrase, laptop-side) was created on the laptop for agent use. The user's main ~/.ssh/id_ed25519 has a passphrase and cannot be used non-interactively. No passwords are stored in this repo.
    • The account's sudo is password-protected; the agent has no sudo. The account was briefly locked by pam_faillock after failed attempts (cleared by waiting).
  • Installed/fixed this session (by the user, via sudo): xorriso, squashfs-tools, mtools; docker enabled and mama in the docker group (docker 29.8.2). podman 6.1.3 rootless also works.
  • Rust: mise's rust shim is broken. Use export PATH=$HOME/.cargo/bin:$PATH (cargo/rustc 1.99.0). Node: $HOME/.local/share/mise/installs/node/26.11.1/bin.
  • Checkout: ~/Projects/archy (NOT sparse), branch arm64-pi-test at b158aac on top of origin/main 2d19d03.

Built artifacts (on the M2, from 1.9.1-alpha)

  • Backend: ~/Projects/archy/image-recipe/build/backend/archipelago — ELF aarch64, 53 MB, reports 1.9.1-alpha-dev, SHA256 b32c8cffa9b512e697dedbccc6799b10180b643ce8b158b4263aec3c67da4f99. Built with CARGO_BUILD_JOBS=4 ARCH=aarch64 image-recipe/scripts/build-backend.sh (native build, ~5 min; output name is archipelago, not archipelago-aarch64, because the host is already aarch64).
  • Frontend: image-recipe/build/frontend/ (69 MB), via npm ci + image-recipe/scripts/build-frontend.sh. The stale 1.8.11 web-ui.tar.gz was deleted.
  • Bitcoin Core 28.4 arm64 image exists on the laptop (image-recipe/build/bitcoin-28.4-aarch64.tar) but is NOT needed for the ISO: the ISO bundles Bitcoin Knots and ~25 other images pulled by the ISO builder itself (--platform linux/arm64). Do not build it for the ISO.

ISO / installer findings (not started)

image-recipe/build-debian-iso.sh wraps image-recipe/_archived/build-auto-installer-iso.sh (archived; OTA tarballs replaced it upstream). It accepts ARCH=arm64 (kernel, grub-efi-arm64 vars) but many x86 assumptions remain:

  • l.328 fips_*_amd64.deb; l.413 amd64-microcode; l.896 grub-efi-amd64-bin grub-pc-bin isolinux syslinux-common
  • l.1095 mksquashfs ... -Xbcj x86; l.1131 grub-mkstandalone -O x86_64-efi
  • l.1174 expects BOOTX64.EFI (arm64: BOOTAA64.EFI)
  • ISO layout (l.1146, 4382-4506) uses isolinux/BIOS hybrid boot
  • Defaults: ARCH=x86_64; DEV_SERVER=archipelago@192.0.2.10 (placeholder) — use DEV_SERVER=localhost to force registry pulls.
  • Debootstrap runs in a --privileged container (needs rootful docker — now OK).
  • The resulting ISO would be generic arm64 UEFI. A Pi 4/5 will not boot it without EDK2/UEFI firmware. Testable in a UEFI ARM VM.
  • Estimate: porting + testing ≈ half a day or more.

Options (user has not chosen yet)

  1. Port the archived ISO builder to arm64 (true installer ISO; longest).
  2. Build a Pi SD/USB image from Debian arm64 (check image-recipe/raspberrypi/ for existing boot config) — likely what to ship.
  3. Manual install on Pi OS Lite per docs/raspberry-pi-test-install.md — fastest way to validate the 1.9.1 build on real hardware.

Agent recommendation: do (3) now to prove backend/frontend on a Pi, then (2). Ask the user whether they have a Pi to test on and which target they want.

Known gaps (from earlier handoff, still true)

Architecture-aware OTA/image selection; barkd x86-only asset; catalog audit; install-ngit.sh already has an aarch64 asset. Git anomaly (missing promisor object f7208e17…) on the laptop only matters if it blocks a command.

Update — Phase 0 progress (later 2026-10-11)

  • Transfer bundle on the M2: ~/arm-bundle-1.9.1/ containing archipelago-aarch64 (same binary/SHA256 as above), web-ui.tar.gz (60 MB), archipelago.service, nginx-archipelago.conf. This is exactly what docs/raspberry-pi-test-install.md Part 2 asks to copy to a Pi.
  • Compatibility check vs Pi OS (Debian trixie, glibc 2.41): binary needs GLIBC <= 2.39 (built on Arch, glibc 2.43) — OK. Dynamically links libssl.so.3, libz, libgcc_s, brotli, zstd (all in trixie; install libssl3t64).
  • Smoke test in debian:trixie-slim linux/arm64 container on the M2: binary loads, no missing libs, prints archipelago 1.9.1-alpha-dev, starts ("Starting Archipelago Bitcoin Node OS"), then exits with "Neither Podman nor Docker is available" (+ sudo systemd-run bootstrap warnings). That is expected in a bare container; a real test needs a systemd host with rootless podman (Pi or arm64 VM). /health was not reachable.
  • NEXT: need a Pi (or arm64 systemd VM on the M2) to finish the Part 3 validation checklist. Then decide on the Pi image recipe (option 2).

Update 2 — arm64 systemd test PASSED (2026-10-11)

Ran the Part 2 install inside a privileged debian:trixie-slim linux/arm64 systemd container on the M2 (Dockerfile: ~/arm-bundle-1.9.1/Dockerfile.systest, image archy-systest, container archy-st). With the gaps below fixed:

  • archipelago.service active; backend GET :5678/health -> 200 (version 1.9.1-alpha, crash_recovery_complete, rpc+sessions up)
  • nginx proxy /health -> 200; UI / -> 200 over http and https
  • Non-fatal warnings only (kdump crashkernel fixup, fips anchors/fipsctl, LND macaroon not present) — container-environment related. Gaps found and documented in docs/raspberry-pi-test-install.md (commit on laptop branch arm64-pi-test): groups debian-tor/fips, dirs under /home/archipelago/.{local/share,config}/containers, /etc/nginx/snippets/* from image-recipe/configs/snippets, TLS cert in /etc/archipelago/ssl/. Not covered (needs a real Pi / VM): rootless podman app install from the UI, real hardware, bitcoind. Still open: ISO/SD image recipe (options above).