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