ADR 0015: Raspberry Pi appliance image¶
- Status: Proposed (becomes Accepted once the image was flashed with Raspberry Pi Imager on real hardware, see decision 7)
- Date: 2026-11-12
- Tracking: #130
Context¶
Waylight runs wherever Docker and Compose run, and multi-arch images
(including arm64) are published and smoke-tested for every release (#43).
That still assumes a Linux server, a terminal and a hand-edited .env.
Many people who would like a start page for their home own a spare Raspberry Pi but no server. For them the shortest path is an appliance: flash an SD card, boot, open a URL. The app is a good fit for that — one static binary without CGO, SQLite in a single file, about 75 MB of memory when idle (ADR 0011) — so the work is almost entirely about packaging and operations, not about the application.
Constraints on a Raspberry Pi differ from a home server:
- Storage is usually an SD card: limited write endurance, corruption on power loss, slow random writes.
- Memory can be as low as 512 MB (Pi Zero 2 W).
- Headless is the norm: no keyboard or monitor during setup.
- Public image: every device is flashed from the same file, so the image must not contain any secret.
- Updates must work without reflashing, or devices will run old versions forever.
Decision¶
-
Base OS: Raspberry Pi OS Lite (64-bit), currently Debian Trixie. It supports every 64-bit board, gets kernel and firmware updates from Raspberry Pi, and includes cloud-init, which Raspberry Pi Imager 2.x uses for its customisation (user, Wi-Fi, SSH key, locale, time zone). Users get the familiar Imager flow instead of a project-specific one. Supported boards: Pi 3B/3B+, 4, 400, 5, 500 and Zero 2 W.
-
Runtime: native systemd service, no Docker in the image. The binary is static, so a container adds nothing but weight on a single-purpose device: a second runtime in memory, image layers on the SD card and a second update path. Isolation comes from systemd instead: a dedicated system user,
ProtectSystem=strict,PrivateDevices, a system call filter and an empty capability set (onlyCAP_NET_BIND_SERVICEto listen on port 80). Without Docker the workarounds needed for the container disappear: Wake-on-LAN broadcasts directly (no relay), the system module reads/procand/sysdirectly. The Docker module is disabled by default on the image. -
Packaging:
.debpackages, built with nfpm, forarm64andamd64. The image installs the same package that any Debian or Ubuntu user can install without Docker. nfpm is a build-time tool only (ADR 0011). Configuration stays environment-based (/etc/waylight/waylight.envloaded withEnvironmentFile=), sointernal/platform/configdoes not change. Data lives in/var/lib/waylight. -
Updates: signed APT repository plus
unattended-upgrades. Packages are published to an APT repository on GitHub Pages, signed with a dedicated key held in GitHub secrets. The image trusts that key viaSigned-Byand installs OS security updates and Waylight releases automatically, with reboots only inside a maintenance window. Pinning a version and rolling back work withapt, mirroringWAYLIGHT_VERSIONfor Docker. -
First boot creates all secrets on the device. A oneshot service generates
SECRET_KEYand a setup token before the app starts for the first time. The setup token is offered only through channels that need physical access or the owner's credentials: the HDMI console, a file on the boot partition of the SD card,sudoover SSH and the journal. Both visible copies are removed once the account exists. CI verifies that the image contains noSECRET_KEY, SSH host keys or password hashes. -
Built and tested in CI on
ubuntu-24.04-arm. Native arm64 runners are free for public repositories, so the image is built without emulation in the release workflow, boot-tested, and attached to the release with checksum, SBOM and provenance attestation. A Raspberry Pi Imager repository file (os_list.json,init_format: cloudinit-rpi) lets users pick the image inside Imager. -
Build method: customise the official Raspberry Pi OS Lite image (result of the spike, #132).
deploy/raspberrypi/build-image.shstarts from the released Lite image, pinned by URL and SHA-256 inbase.env, grows the root partition, installs the package in a chroot on a native arm64 runner (no emulation), adds the files fromrootfs/and zeroes the free space. The result is byte for byte Raspberry Pi OS Lite plus a small, reviewable layer, so cloud-init, the first-boot resize and Imager's customisation behave exactly as on the official image.
Measured in CI on ubuntu-24.04-arm (2026-11-12): image build 220–260 s,
boot test 25 s, whole job about 6.5 minutes; .img.xz 557.5 MB
(the base is 525 MB). The size is a budget in budgets.json.
Not chosen: pi-gen rebuilds Raspberry Pi OS from packages, so every
build is much longer and the result only approximates the released image;
rpi-image-gen starts from its own minimal Debian base with a
different first-boot path and is still under active development. Neither
was built in the spike: the customised image already met every goal, and
switching later only touches deploy/raspberrypi/.
Still to verify on hardware before this ADR is accepted: flashing with Raspberry Pi Imager 2.x including its customisation (Wi-Fi, user, SSH, hostname) on a Pi 4 or 5.
- SD-card care. journald size-limited,
noatime, swap as Raspberry Pi OS configures it, the existing WAL +synchronous=NORMALSQLite settings (consistent after a power loss, at worst the last transaction is lost), and a systemd watchdog through a smallsd_notifyhelper ininternal/platformthat is a no-op outside systemd (#136).
Alternatives considered¶
- Docker inside the image (Raspberry Pi OS + Docker +
compose.yaml). Least new code and identical to the documented setup, butdockerdandcontainerdpermanently in memory, more SD-card writes, two update paths (apt and images) and the WoL relay and/hostmounts that only exist because of the container. Users who want Docker can keep using the Compose setup on any Pi. - DietPi or Armbian as base. Good optimisations for small boards, but their own first-boot systems and update tools; Imager customisation would not work the same way, and a third party would sit between us and kernel updates.
- Buildroot or Yocto (read-only, A/B updates). The most robust
appliance, but a large maintenance burden for a two-person project, no
apt, and every package has to be built from source. - Only document "install the .deb on Raspberry Pi OS". Useful and part of this decision (decision 3), but still requires a terminal; it does not reach the people the image is for.
Consequences¶
- A second distribution channel to maintain: packaging, APT repository, image build and the signing key. The release workflow grows by two jobs.
- The application code stays unchanged except for the generic systemd
notify helper; the dependency rule (ADR 0001) is unaffected because all
Pi-specific files live in
packaging/anddeploy/raspberrypi/. - Native
.debpackages also benefit users on other Debian-based machines who do not want Docker. - The image size becomes a budget in
budgets.json(ADR 0011). - The Docker setup remains the primary, fully supported way to run Waylight on a server; documentation presents both.
- One image, two display modes (#140). After the account setup, Pi installs ask whether the device is a server only (default) or should also show the dashboard full-screen on an attached display; the choice can be changed later in the settings. Kiosk components (a minimal Wayland compositor and browser) are a separate package installed on demand, so the default image stays lean. The app stays unprivileged: it can only write a requested mode into its state directory, and a root-owned systemd path unit applies it with a fixed, validating script.