alamos-alpine-kiosk/README.md
Jonas Leder f02ca47f3c
Some checks failed
ci / publish-amweb-version (push) Has been skipped
ci / build-image (push) Failing after 8m30s
README: restore sections after CI rewrite
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 10:46:52 +01:00

14 KiB

alamos-alpine-kiosk

Builds a diskless Alpine Linux kiosk image: boots straight into a fullscreen Chromium window (Wayland, via cage), with SSH, VNC, and self-update built in.

Updates are applied via RAUC into two interchangeable A/B root slots, so an update is always written to the inactive slot while the device keeps running from the current one, and a slot that fails to boot cleanly is rolled back automatically by GRUB.

How it boots

The image runs entirely from RAM, from one of two identical root slots plus a separate, persistent data partition, all on the same boot media (USB stick):

ALPINEESP          FAT32, ~100MiB -- a tiny GRUB EFI stub (UEFI only)
                    that finds ALPINEDATA by label and chainloads the
                    real grub.cfg from there.
ALPINEKIOSK_A       ext4, RAUC slot "rootfs.0":
                      boot/vmlinuz-lts       kernel
                      boot/initramfs-lts     custom initramfs (build/initramfs-init)
                      boot/rootfs.squashfs   the whole Alpine system, read-only
ALPINEKIOSK_B       ext4, RAUC slot "rootfs.1" -- identical layout, the
                    second slot.
ALPINEDATA          ext4, rest of the disk -- persistent, never touched
                    by a RAUC install:
                      boot/grub/grub.cfg   the real GRUB config: A/B
                                           slot selection, 3s manual
                                           override menu
                      boot/grub/grubenv    GRUB's slot-selection state
                                           (ORDER, per-slot _OK/_TRY)
                      kiosk.conf           per-device configuration
                      rauc.status          RAUC's status file

At boot, GRUB (BIOS: real grub-install-style i386-pc core image; UEFI: the ESP stub chainloading grub.cfg) picks a slot using grubenv's ORDER and each slot's _OK/_TRY counters, shows a 3 second menu ("Slot A" / "Slot B") so an operator at the console can override that choice, then boots the chosen slot with root=LABEL=ALPINEKIOSK_A (or _B) on the kernel command line. The initramfs reads that label, mounts the slot read-only, loop-mounts rootfs.squashfs from it, layers a tmpfs overlay on top for writability, bind-mounts ALPINEDATA into the new root at /media/bootdev (symlinked as /kiosk.conf), and switch_roots into it. Nothing is ever written back into the squashfs or the booted slot itself; all runtime state lives in RAM and is discarded on reboot except for whatever's written to /media/bootdev (config, grubenv) or, via RAUC, to the other, inactive slot.

tty1 autologs in as kiosk, whose .profile execs /usr/local/bin/start-kiosk.sh, which runs cage (a Wayland compositor built specifically for single-app kiosks) with Chromium in --kiosk fullscreen mode pointed at KIOSK_URL. wayvnc runs as a system service and exposes the same Wayland session over VNC on port 5900.

Updating and rollback

kiosk-update.sh (run periodically by crond, see kiosk.conf below) downloads a signed .raucb bundle and hands it to rauc install, which verifies its signature and writes it into whichever slot isn't currently running -- the running slot is never touched. On success the new slot is marked active and, if AUTO_REBOOT=true, the device reboots into it.

If a newly installed slot fails to reach a healthy boot, it's rolled back automatically, with no involvement from kiosk-update.sh: grub.cfg increments that slot's _TRY counter on every boot attempt (even ones that never get past the kernel), and the rauc-mark-good OpenRC service only resets _TRY and confirms the slot once Alpine's default runlevel is reached. After _TRY exceeds the limit without a confirmation, GRUB prefers the other, previously-good slot on its own.

Repository layout

  • build/build-image.sh — orchestrates the whole build: installs Alpine packages into a chroot-able rootfs via apk --root, copies in the files under build/rootfs/, builds the custom initramfs and RAUC (from source — Alpine ships no rauc package), squashes the rootfs, builds the ext4 slot image and GRUB boot files, and packages dist/<name>-<version>.tar.gz (first-install payload), dist/<name>-<version>.raucb (signed update bundle) and dist/latest.json.
  • build/rauc-hook.sh — bundled inside the .raucb; re-labels whichever slot RAUC just wrote (ALPINEKIOSK_A/_B), since the raw image itself carries a neutral label.
  • build/initramfs-init — the initramfs's PID 1 (busybox ash script).
  • build/rootfs/ — files overlaid onto the built system: OpenRC services (kiosk, wayvnc, rauc-mark-good), /etc/rauc/system.conf, the periodic auto-update job, and /usr/local/bin/{start-kiosk,kiosk-apply-config,kiosk-update}.sh.
  • config/kiosk.conf.example — template for the per-device config file.
  • install/install-usb.sh — formats a USB disk into the ESP, A/B slot and data partition layout above, and installs a built release onto it, bootable via real GRUB on both BIOS and UEFI.
  • .forgejo/workflows/ci.yml — builds the image in an alpine:3.24 container job.

Building

sudo ALPINE_VERSION=3.24 KIOSK_VERSION=42 bash build/build-image.sh

Requires root (apk needs to populate --root), plus apk, squashfs-tools, cpio, coreutils/findutils, e2fsprogs (for mke2fs -d, which builds the ext4 slot image directly from a directory tree, no loop-mount needed), grub/grub-efi/grub-bios (for the UEFI stub and the bundled BIOS install tools), and meson/ninja/ build-base/pkgconf/glib-dev/openssl-dev to compile RAUC from source (Alpine ships no rauc package) on the host. No QEMU/ virtualization needed — this only works because the build host and target are both x86_64; the one privileged operation is apk internally chroot()ing to run package post-install scripts, which only needs CAP_SYS_CHROOT (part of the default container capability set).

For real deployments, also set RAUC_CERT_PATH/RAUC_KEY_PATH to a cert/key pair generated once (see build-image.sh's ensure_rauc_keys()) and reused on every build — without them, builds fall back to an ephemeral throwaway signing cert (loud warning), whose bundles no device that trusts a different cert can install.

Output: dist/alpine-kiosk-<KIOSK_VERSION>.tar.gz (first-install payload), dist/alpine-kiosk-<KIOSK_VERSION>.raucb (signed update bundle) and dist/latest.json.

CI

.forgejo/workflows/ci.yml runs the build in an alpine:3.24 container job (Forgejo Actions), using the run number plus 129100 as KIOSK_VERSION so versions keep growing from the old GitLab pipeline ids. Repo secrets: RAUC_SIGN_CERT/RAUC_SIGN_KEY (PEM of the persistent signing pair) and MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY/MINIO_BUCKET for the release upload (stable on the default branch, beta/ on develop). A daily schedule republishes the AMweb vendor ETag for Renovate.

Installing to a USB stick

sudo install/install-usb.sh /dev/sdX dist/alpine-kiosk-42.tar.gz [my-kiosk.conf]

This wipes /dev/sdX, creates the ESP + ALPINEKIOSK_A + ALPINEKIOSK_B + ALPINEDATA layout described above (both slots seeded with identical content so the disk boots either one immediately), and installs real GRUB for both BIOS and UEFI using the grub-mkimage/ grub-bios-setup/grub-editenv binaries and i386-pc module set bundled in the release tarball itself (under tools/) — no grub package needed on the installer host. Requires parted, mkfs.ext4, mkfs.vfat, wipefs, dd, e2label (Alpine: e2fsprogs + e2fsprogs-extra, the latter is where e2label actually lives). If no kiosk.conf is given and the target doesn't already have one, the example template is installed — edit it on the device before first boot (or mount the ALPINEDATA partition from another machine).

kiosk.conf

Lives at the root of the ALPINEDATA partition (symlinked to /kiosk.conf at runtime). See config/kiosk.conf.example for the full set of options:

  • KIOSK_URL — page Chromium opens fullscreen. Defaults to http://localhost/setup, the bundled AMweb app's own setup page (see "Bundled AMweb app" below).
  • HOSTNAME — system hostname (defaults to alpine-kiosk).
  • SSH_PUBKEY (_2, _3, ...) — authorized keys for root over SSH (password auth is disabled).
  • ROOT_PASSWORD — optional root password for local console/recovery-shell login only; SSH root login always requires SSH_PUBKEY regardless (PermitRootLogin prohibit-password is set at the image level and ignores this). Leave blank to keep root locked entirely.
  • VNC_PASSWORD — optional wayvnc password; empty means unauthenticated.
  • NET_MODE (ethernet/wifi), WIFI_SSID, WIFI_PSK, WIFI_IFACE, ETH_IFACE.
  • TIMEZONE — IANA/tzdata zone name (e.g. Europe/Berlin); defaults to UTC if unset or unrecognized.
  • NTP_SERVERS — space-separated list of NTP servers/pools for time sync (chronyd, always running); defaults to pool.ntp.org if unset.
  • AUTO_UPDATE, UPDATE_URL, UPDATE_INTERVAL_MINUTES — periodic check against a latest.json manifest (the same format build-image.sh produces); if newer, downloads the .raucb bundle and hands it to rauc install, which verifies its signature and writes it into the inactive slot (see "Updating and rollback" above) — the currently running slot is never touched.
  • AUTO_REBOOT — reboot automatically once an update is applied.

Applied at boot by the kiosk OpenRC service (kiosk-apply-config.sh), which runs before networking/sshd/wayvnc.

Bundled AMweb app

build-image.sh's bundle_amweb() downloads https://files.alamos-gmbh.com/AMweb/AMweb.zip at build time and bundles its dist/alarmmonitor-web contents into /var/www/amweb (override the source with AMWEB_ZIP_URL). It's served locally, loopback-only, by a standalone nginx instance (etc/nginx/amweb.conf and etc/init.d/amweb, independent of Alpine's own default nginx setup, which isn't used) on 127.0.0.1:80, with try_files SPA fallback so client-side routes like /setup return index.html instead of a 404.

AMweb's setup (entered once at http://localhost/setup) is saved by the browser into Chrome's localStorage. Since the whole root filesystem is a fresh RAM overlay every boot, start-kiosk.sh symlinks just that one directory (~/.config/chromium/Default/Local Storage, prepared and chowned as root by kiosk-apply-config.sh) onto the ALPINEDATA partition, so setup survives a reboot — the rest of the Chrome profile (cache, cookies, IndexedDB, ...) stays ephemeral.

Known limitations / things to verify on real hardware

  • The initramfs bundles the entire stock Alpine module set (not a curated subset) precisely so no target hardware's storage/USB controller gets silently missed -- this makes initramfs-lts large (~100MiB+) and the whole release correspondingly bigger, trading image size for not needing to debug missing-driver boot failures per board.
  • wayvnc currently mirrors the compositor read-only from other clients' perspective by default configuration; adjust wayvnc-wait.sh/kiosk-apply-config.sh if you want remote input.
  • Wi-Fi firmware isn't bundled (linux-firmware is large); add the specific linux-firmware-<chipset> package to PACKAGES in build-image.sh for your target adapter.
  • ROOTFS_SLOT_SIZE_MIB (default 2048) fixes each RAUC slot partition's size at install time, from the release tarball's own slot.img size — if the built system grows past that (e.g. more chromium-lang locales, EXTRA_FIRMWARE_PKGS), raise it and reinstall; existing devices updated in the field can't grow their already-partitioned slots.
  • BIOS boot now goes through this project's own bundling of grub-mkimage/grub-bios-setup (see bundle_grub_tools() in build-image.sh) rather than a grub-install most other projects rely on, since the target device is known and grub-install's own device-detection isn't needed — verify it boots on real BIOS/CSM hardware (and a spare disk/VM) before relying on it, the same way you would any new bootloader integration.
  • RAUC's GRUB slot-selection logic (grub.cfg's _TRY counters, the rauc-mark-good service) is this project's own implementation of the documented ORDER/<slot>_OK/<slot>_TRY grubenv contract RAUC's GRUB backend expects, not a copy of RAUC's own reference script — test the rollback path deliberately (see the "Simulate a bad update" step below) rather than assuming it's identical to other RAUC+GRUB deployments you may have seen. Verified end-to-end in QEMU/OVMF (ESP stub -> ALPINEDATA chainload -> menu -> slot boot attempt), which is also how a real bug was caught and fixed here: GRUB script has no $((...)) arithmetic (that's bash, not GRUB's script grammar), which silently corrupted the _TRY-incrementing menuentry blocks and dropped straight to a grub rescue/grub> prompt with no visible error -- if you ever need to touch grub.cfg's generation again, boot-test the change the same way rather than trusting it by reading.

Testing an update / rollback

  1. Build, then serve dist/ locally (python3 -m http.server from dist/) and point a test device's UPDATE_URL at http://<host>:8000/latest.json.
  2. Bump KIOSK_VERSION and rebuild; kiosk-update.sh (or /etc/periodic/15min/kiosk-update) should download the new .raucb, rauc install it into the inactive slot, and — with AUTO_REBOOT=true — reboot into it. rauc status should show the new slot active and, once rauc-mark-good has run, good.
  3. To exercise rollback, corrupt the inactive slot after an install but before rebooting into it (e.g. dd if=/dev/zero of=/dev/disk/by-label/ALPINEKIOSK_B bs=1M count=8 if B is inactive) and reboot: GRUB's menu should fall back to slot A once B's _TRY count is exceeded, rather than hanging on a broken slot.