stormux/pi4/build/README.md

Stormux Pi Image Builder

Stormux provides an Arch-based Raspberry Pi image that already includes Fenrir, Orca, and other screen-reader friendly defaults. This repository hosts the scripts maintained by the Stormux community (originally crafted by Storm) so anyone can rebuild the image, customize the overlay, and share accessible Pi spins.

Purpose & Scope

This repo captures the complete build pipeline for the Stormux Raspberry Pi images: downloading Arch Linux ARM, layering the accessible defaults, compiling Fenrir and helper tools, and producing a ready-to-flash .img. Running the script yourself lets you reproduce the same system the project ships for the Pi 4/400, tweak it, and publish new spins without reverse-engineering the original release.

What You Need

• A 64-bit Arch Linux host (bare metal or VM) with at least 20 GB free disk space.
• Root access on that host. The builder partitions loopback devices and must run as root.
• Required packages: arch-install-scripts, dosfstools, parted, wget, qemu-user-static, qemu-user-static-binfmt, plus standard developer tools that Arch already ships.
• A Raspberry Pi 4/400 or similar board (a Pi 3 works with the -v 32 option) and a microSD card (8 GB or larger recommended).

Install dependencies on the build host with:

sudo pacman -S arch-install-scripts dosfstools parted wget qemu-user-static qemu-user-static-binfmt

Getting the Source

Clone the canonical repo (or your fork) someplace with plenty of space:

git clone https://git.stormux.org/storm/stormux.git
cd stormux

All build logic lives in pi4/. The pi4/files/ tree mirrors the root filesystem you want inside the image (configs in etc, helper scripts in usr/local/bin, and so on).

Where to Run the Builder

The script is designed for an x86_64 Arch host so it can emulate ARM binaries with QEMU while building. You can run it natively on an ARM board (including a Pi) running Arch or Stormux, but expect much longer build times and make sure the same packages are installed. Whatever the CPU, you must run as root and ensure /mnt is free so the loopback rootfs can mount safely.

Building Your First Image

1. Become root (sudo -i) so the script can create loop devices and mount them.
2. From /path/to/stormux, run:

   sudo ./pi4/build/build-stormux.sh -v 64 -l en_US -s 6
   

   • -v 64 builds the aarch64 image (use -v 32 for the Pi 3/armv7h).
   • -l en_US selects the locale (use es_ES, fr_FR, etc.).
   • -s 6 sets the image size in gigabytes.
   • Add -n my-stormux.img to override the default filename.
3. Grab coffee. The script downloads the latest Arch Linux ARM tarball, provisions packages (Fenrir, Orca, NetworkManager, PipeWire, etc.), copies the overlay from pi4/files/, and cleans up.
4. When the build-stormux.sh command returns, you should have an .img file in your working directory (for example stormux-pi4-aarch64-YYYY-MM-DD.img).

If the build is interrupted, run sudo umount -R /mnt && sudo losetup -D to be sure nothing is still mounted.

Customizing the Image

• Overlay files: Add or edit files in pi4/files/ using the same paths they should have inside the Pi. Example: to add a custom MOTD, edit pi4/files/etc/motd.
• Packages: Edit the package list inside pi4/build/build-stormux.sh (search for pacman -Su --needed). Add or remove entries as needed, then rebuild.
• AUR components: The script already compiles Fenrir (fenrir-git), growpartfs, log2ram, and yay. To add more AUR packages, append them to the aurPackages array near the middle of the script.
• First-boot behavior: Modify pi4/files/usr/local/bin/configure-stormux to change the guided setup that runs when the image boots the first time.

Remember to keep permissions sensible (chmod 755 for scripts, 644 for configs) so rsync copies them correctly.

Keeping Up with Upstream Updates

Storm and other contributors actively improve these scripts. To sync your local clone with the latest changes:

cd /path/to/stormux
git pull --ff-only

Rebuild after pulling so your custom image inherits any upstream fixes (new packages, service tweaks, security patches). If you maintain your own fork, merge or rebase onto the upstream main branch before publishing updated images.

Flashing and Booting

1. Verify the image:

   ls -lh stormux-pi4-*.img
   

2. Write it to an SD card (replace /dev/sdX with your card, not a partition):

   sudo dd if=stormux-pi4-aarch64-*.img of=/dev/sdX bs=4M status=progress conv=fsync
   

3. Insert the card into your Pi 4/400 and power it on. You should hear Fenrir start speaking once the user session loads.
4. Log in using the default credentials (username stormux, password stormux). Root uses root/root until you change it.
5. Run sudo configure-stormux (or follow the automatic prompt) to finish the guided setup: configure networking via nmtui, update the clock, optionally resize the SD card with growpartfs, and toggle Fenrir’s layout.

Testing Without Hardware

You can boot the image in a container to verify services before flashing:

sudo systemd-nspawn -i stormux-pi4-aarch64-*.img --boot

Use machinectl to connect to the console and ensure critical services start. For unit files you edit, run systemd-analyze verify path/to/unit inside the container or the Pi.

Troubleshooting Tips

• Locale or package errors: Ensure your host’s pacman keyring is up to date (sudo pacman -Sy archlinux-keyring).
• Loop device cleanup: After failures run sudo losetup -a to find stray devices, then sudo losetup -d /dev/loopX.
• Disk too small: Increase the -s argument or remove packages.
• Accessibility tweaks: If Fenrir is too quiet or you prefer Orca, install the orca package inside the overlay and add it to the autostart configuration in pi4/files/etc/xdg/autostart/.

Sharing Your Image

When you are happy with your customizations:

1. Rebuild so you have a clean .img file named clearly (for example, stormux-pi4-a11y-v1.img).
2. Compress it (xz -T0 -z stormux-pi4-a11y-v1.img).
3. Publish the image along with the exact commit you built from and any extra scripts you used. The README and AGENTS.md in this repo explain the layout so others can reproduce your work.

Huge Thanks to Storm

Storm did the heavy lifting—curating packages, wiring up Fenrir/Orca defaults, scripting the first-boot assistant, and sharing the whole build process so the community can remix it. This repo exists because accessibility was treated as a first-class feature from day one, and the documentation lets anyone extend that work. If the image improves your Pi experience, consider contributing improvements or telling Storm thanks.

With these steps you can take the same base image Storm released, tweak it to your needs, and ship a fully accessible Arch image for other Pi fans. Happy hacking!