# ARM64 Raspberry Pi 5 Testing Guide

## Prerequisites

- Raspberry Pi 5 (4GB+ RAM recommended)
- USB flash drive (16GB+) for the installer
- MicroSD card or NVMe SSD for the target install
- Monitor + keyboard (or serial console for headless setup)
- Ethernet connection (WiFi can be configured after install)

## Building the ARM64 ISO

On the build server (192.168.1.228):

```bash
cd ~/archy/image-recipe
sudo ARCH=arm64 ./build-auto-installer-iso.sh
# Output: results/archipelago-installer-arm64.iso
```

## Flashing to USB

```bash
# On macOS
diskutil list  # identify USB drive
diskutil unmountDisk /dev/diskN
sudo dd if=results/archipelago-installer-arm64.iso of=/dev/rdiskN bs=4m

# On Linux
sudo dd if=results/archipelago-installer-arm64.iso of=/dev/sdX bs=4M status=progress
```

Or use Balena Etcher for a GUI approach.

## Testing Checklist

### Boot & Install
- [ ] RPi 5 boots from USB drive (may need to enable USB boot in EEPROM)
- [ ] Auto-installer detects target disk (NVMe/SD)
- [ ] Installation completes without errors
- [ ] System reboots into installed OS

### First Boot
- [ ] Archipelago service starts (`systemctl status archipelago`)
- [ ] Nginx starts and serves UI
- [ ] Web UI loads in browser at `http://<pi-ip>`
- [ ] Onboarding flow completes
- [ ] Login works with default password

### Container Stack
- [ ] Podman runs on ARM64 (`podman version`)
- [ ] Bitcoin Knots installs and syncs
- [ ] LND installs and connects to Bitcoin
- [ ] Electrs installs and indexes
- [ ] Mempool installs and shows data
- [ ] FileBrowser installs and serves files

### Performance
- [ ] Backend response time < 200ms for RPC calls
- [ ] UI renders smoothly (no jank)
- [ ] Container startup time reasonable (< 30s per app)
- [ ] Memory usage stable (no leaks over 24h)

## Known RPi 5 Considerations

1. **USB Boot**: RPi 5 needs EEPROM update for USB boot. Run `sudo rpi-eeprom-update` on a stock Raspberry Pi OS first.
2. **NVMe**: RPi 5 supports NVMe via the M.2 HAT. Recommended for performance.
3. **Power**: Use the official 27W USB-C power supply. Underpowered supplies cause throttling.
4. **Thermals**: Consider a heatsink or active cooling case for sustained Bitcoin node operation.
5. **Storage**: Bitcoin blockchain requires ~600GB+. Use NVMe or external SSD.

## Reporting Issues

Document any ARM64-specific issues found during testing:
- Architecture-specific container failures
- Performance differences vs x86_64
- Hardware compatibility problems
- Missing kernel modules or firmware