README: restore sections after CI rewrite
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
b99f608b69
commit
f02ca47f3c
1 changed files with 128 additions and 0 deletions
128
README.md
128
README.md
|
|
@ -133,3 +133,131 @@ versions keep growing from the old GitLab pipeline ids. Repo secrets:
|
|||
`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
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue