README.md for the pi4 build-stormux.sh script

pi4/build/README.md

@@ -0,0 +1,96 @@
+# 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:
+```bash
+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:
+```bash
+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:
+   ```bash
+   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:
+```bash
+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:
+   ```bash
+   ls -lh stormux-pi4-*.img
+   ```
+2. Write it to an SD card (replace `/dev/sdX` with your card, not a partition):
+   ```bash
+   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:
+```bash
+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!