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 viaapk --root, copies in the files underbuild/rootfs/, builds the custom initramfs and RAUC (from source — Alpine ships noraucpackage), squashes the rootfs, builds the ext4 slot image and GRUB boot files, and packagesdist/<name>-<version>.tar.gz(first-install payload),dist/<name>-<version>.raucb(signed update bundle) anddist/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 analpine:3.24container 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 tohttp://localhost/setup, the bundled AMweb app's own setup page (see "Bundled AMweb app" below).HOSTNAME— system hostname (defaults toalpine-kiosk).SSH_PUBKEY(_2,_3, ...) — authorized keys forrootover SSH (password auth is disabled).ROOT_PASSWORD— optional root password for local console/recovery-shell login only; SSH root login always requiresSSH_PUBKEYregardless (PermitRootLogin prohibit-passwordis 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 toUTCif unset or unrecognized.NTP_SERVERS— space-separated list of NTP servers/pools for time sync (chronyd, always running); defaults topool.ntp.orgif unset.AUTO_UPDATE,UPDATE_URL,UPDATE_INTERVAL_MINUTES— periodic check against alatest.jsonmanifest (the same formatbuild-image.shproduces); if newer, downloads the.raucbbundle and hands it torauc 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-ltslarge (~100MiB+) and the whole release correspondingly bigger, trading image size for not needing to debug missing-driver boot failures per board. wayvnccurrently mirrors the compositor read-only from other clients' perspective by default configuration; adjustwayvnc-wait.sh/kiosk-apply-config.shif you want remote input.- Wi-Fi firmware isn't bundled (
linux-firmwareis large); add the specificlinux-firmware-<chipset>package toPACKAGESinbuild-image.shfor your target adapter. ROOTFS_SLOT_SIZE_MIB(default 2048) fixes each RAUC slot partition's size at install time, from the release tarball's ownslot.imgsize — if the built system grows past that (e.g. morechromium-langlocales,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(seebundle_grub_tools()inbuild-image.sh) rather than agrub-installmost other projects rely on, since the target device is known andgrub-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_TRYcounters, therauc-mark-goodservice) is this project's own implementation of the documentedORDER/<slot>_OK/<slot>_TRYgrubenv 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 ->ALPINEDATAchainload -> 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-incrementingmenuentryblocks and dropped straight to agrub rescue/grub>prompt with no visible error -- if you ever need to touchgrub.cfg's generation again, boot-test the change the same way rather than trusting it by reading.
Testing an update / rollback
- Build, then serve
dist/locally (python3 -m http.serverfromdist/) and point a test device'sUPDATE_URLathttp://<host>:8000/latest.json. - Bump
KIOSK_VERSIONand rebuild;kiosk-update.sh(or/etc/periodic/15min/kiosk-update) should download the new.raucb,rauc installit into the inactive slot, and — withAUTO_REBOOT=true— reboot into it.rauc statusshould show the new slot active and, oncerauc-mark-goodhas run, good. - 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=8ifBis inactive) and reboot: GRUB's menu should fall back to slotAonceB's_TRYcount is exceeded, rather than hanging on a broken slot.