diff --git a/debian-live-config/README.md b/debian-live-config/README.md index 1111d663..bbe01346 100644 --- a/debian-live-config/README.md +++ b/debian-live-config/README.md @@ -48,6 +48,36 @@ the user's library so a drive moved between hosts keeps its full state: config/ ← bind-mounted to /etc/postgresql ``` +## Booting via Ventoy or other multiboot USBs + +Booting WROLPi via Ventoy, YUMI, Easy2Boot, AIO Boot, GLIM, or any other +tool that loop-mounts the ISO **works**, but only in ephemeral mode. + +When the live medium appears under `/dev/loop*`, `/dev/dm-*`, or +`/dev/mapper/*` (the kernel's tell-tale for a loop/device-mapper-backed +file rather than a real partition), `wrolpi-bootstrap.sh` refuses to +create a persistence partition. The underlying disk in that case is the +user's Ventoy stick, not a blank target — appending a new ext4 partition +to it would risk corrupting the user's other ISOs and data. + +Instead the script mounts a `tmpfs` at `/media/wrolpi` (sized to half of +RAM by default), and the rest of the boot is unchanged. Postgres +bind-mounts and DB initialisation all succeed, just into RAM. The user +sees a "Running ephemerally…" notice in the first-boot dialog. + +Everything written to the WROLPi library — downloads, archives, video +metadata, the database — is lost on reboot. This mode is intended for +trying WROLPi out without committing a USB stick; for any real use, +flash the ISO directly to its own drive with `dd` or Etcher. + +Direct (dd/Etcher) boot is distinguished by the live medium living under +`/dev/sd*`, `/dev/nvme*`, or `/dev/mmcblk*`; this is the only shape +where `wrolpi-bootstrap.sh` will touch the partition table. + +(Future work: integrate with Ventoy's native `persistence.dat` flow so +the user can opt into a persistent ephemeral-style image without +needing a dedicated drive.) + ## Implementation status - [x] **Phase 1 — merged live + chroot config**: Single `debian-live-config/` @@ -61,6 +91,10 @@ the user's library so a drive moved between hosts keeps its full state: (We previously tried Calamares-as-the-installer; the XFCE desktop-icon click path proved unreliable in the wrolpi auto-login session and the upstream d-i path is better-tested.) +- [x] **Phase 3 — Ventoy/multiboot safety**: `wrolpi-bootstrap.sh` + detects when it's been booted via a loop-mounted ISO (Ventoy and + friends) and falls back to a tmpfs-backed `/media/wrolpi` instead + of writing a new partition onto the user's multiboot stick. - [ ] **Release**: CI on tag, hosting, wrolpi.org docs. ## References diff --git a/debian-live-config/config/includes.chroot/usr/local/sbin/wrolpi-bootstrap.sh b/debian-live-config/config/includes.chroot/usr/local/sbin/wrolpi-bootstrap.sh index a5b12c03..073ddf4d 100644 --- a/debian-live-config/config/includes.chroot/usr/local/sbin/wrolpi-bootstrap.sh +++ b/debian-live-config/config/includes.chroot/usr/local/sbin/wrolpi-bootstrap.sh @@ -1,26 +1,33 @@ #!/usr/bin/env bash # WROLPi bootstrap — runs at every boot via wrolpi-bootstrap.service. -# Idempotent throughout. Works in all three deployment shapes: +# Idempotent throughout. Works in all four deployment shapes: # -# 1. Live USB, first boot. No persistence partition exists. This script -# creates one in the free space at the end of the boot drive, formats it -# as ext4 (label `persistence`), writes a persistence.conf so future -# boots pick it up automatically via live-boot, bind-mounts the -# persistence root over /media/wrolpi, creates the Postgres cluster -# under /media/wrolpi/config/postgresql/, runs initialize_api_db.sh, -# and enables the WROLPi runtime services. +# 1. Live USB (direct), first boot. No persistence partition exists. +# This script creates one in the free space at the end of the boot +# drive, formats it as ext4 (label `persistence`), writes a +# persistence.conf so future boots pick it up automatically via +# live-boot, bind-mounts the persistence root over /media/wrolpi, +# creates the Postgres cluster under /media/wrolpi/config/postgresql/, +# runs initialize_api_db.sh, and enables the WROLPi runtime services. # -# 2. Live USB, subsequent boot. live-boot's initramfs has already applied -# the /media/wrolpi bind mount from persistence.conf. Cluster and DB -# already exist. Most steps no-op; we always regenerate the leaf TLS -# cert and ensure services are enabled. +# 2. Live USB (direct), subsequent boot. live-boot's initramfs has +# already applied the /media/wrolpi bind mount from persistence.conf. +# Cluster and DB already exist. Most steps no-op; we always +# regenerate the leaf TLS cert and ensure services are enabled. # -# 3. Installed (Calamares). No live medium present; partition-creation -# branch is skipped. /media/wrolpi is mounted via /etc/fstab on an -# external drive, or is a plain directory on the root filesystem if -# the user installed without one. The Postgres bind-mounts happen at -# every boot here because /etc/fstab doesn't own them — see Before= -# in the .service unit. +# 3. Live USB (loop / Ventoy / multiboot). The ISO is loop-mounted by a +# multiboot tool, so we cannot safely write a new partition to the +# underlying disk (it's the user's Ventoy stick, not a blank target). +# /media/wrolpi is backed by tmpfs and everything runs from RAM. All +# user data is lost on reboot. Surfaced to the user via the +# first-boot zenity dialog. +# +# 4. Installed. No live medium present; partition-creation branch is +# skipped. /media/wrolpi is mounted via /etc/fstab on an external +# drive, or is a plain directory on the root filesystem if the user +# installed without one. The Postgres bind-mounts happen at every +# boot here because /etc/fstab doesn't own them — see Before= in the +# .service unit. set -euo pipefail @@ -49,27 +56,56 @@ note_action() { SUMMARY="${SUMMARY}- $1 progress "Preparing WROLPi..." -# --- Detect Live vs Installed ------------------------------------------- -# Live: one of the live-boot mount points is active and points at our USB. -# Installed: none of them exist; this script proceeds straight to the -# Postgres bind-mount section. +# --- Detect deployment mode --------------------------------------------- +# Three mutually-exclusive shapes: +# +# direct Live USB flashed with dd/Etcher: the ISO partition is a +# real partition on a real disk. Create + manage a +# persistence partition on that disk. +# +# loop Live medium is a loop or device-mapper node — typical +# of Ventoy, YUMI, Easy2Boot, GLIM, AIO Boot, etc. The +# underlying block device is the user's data drive; we +# must NOT try to sfdisk-append a partition onto it. +# Run ephemerally: /media/wrolpi backed by tmpfs, lost +# on reboot. +# +# installed No live medium at all. Skip partition logic entirely; +# /media/wrolpi is either on /etc/fstab or a plain dir +# on the root filesystem. +MODE=installed BOOT_DRIVE="" +LIVE_MEDIUM="" for mp in /usr/lib/live/mount/medium /run/live/medium /lib/live/mount/medium; do if part=$(findmnt -nr -o SOURCE "$mp" 2>/dev/null) && [ -n "$part" ]; then - BOOT_DRIVE="/dev/$(lsblk -no PKNAME "$part")" - log "live medium $part on $BOOT_DRIVE" + LIVE_MEDIUM=$part + case "$part" in + /dev/sd*|/dev/nvme*|/dev/mmcblk*) + MODE=direct + BOOT_DRIVE="/dev/$(lsblk -no PKNAME "$part")" + log "live medium $part on $BOOT_DRIVE (mode: direct)" + ;; + /dev/loop*|/dev/dm-*|/dev/mapper/*) + MODE=loop + log "live medium $part is a loop/dm device (mode: loop — ephemeral)" + ;; + *) + MODE=loop + log "live medium $part has unrecognised shape (mode: loop — safe default)" + ;; + esac break fi done -if [ -z "$BOOT_DRIVE" ]; then +if [ "$MODE" = "installed" ]; then log "no live medium detected — running in Installed mode" fi -# --- Find or create persistence partition (Live only) ------------------- +# --- Find or create persistence partition (direct mode only) ------------ -if [ -n "$BOOT_DRIVE" ]; then +if [ "$MODE" = "direct" ]; then PERSIST_PART=$(blkid -L persistence 2>/dev/null || true) if [ -z "$PERSIST_PART" ]; then progress "Creating persistence partition on $BOOT_DRIVE..." @@ -156,6 +192,25 @@ EOF fi fi +# --- Ephemeral (loop mode) ---------------------------------------------- +# Booted via Ventoy / multiboot tool / loop-mounted ISO. We cannot tell +# which underlying disk is the user's data drive — appending a partition +# would risk corrupting their Ventoy stick or whatever else they had on +# that device. Run from RAM instead. Anything written to /media/wrolpi +# vanishes on reboot, but the rest of WROLPi (Postgres bind-mounts, +# config layout, services) works identically. + +if [ "$MODE" = "loop" ]; then + if ! mountpoint -q /media/wrolpi; then + mkdir -p /media/wrolpi + # No explicit size= — defaults to half-RAM, plenty for an + # exploratory session and capped so we can't OOM the box. + mount -t tmpfs -o mode=0755 tmpfs /media/wrolpi + log "ephemeral mode: /media/wrolpi is tmpfs (data lost on reboot)" + fi + note_action "Running ephemerally from RAM (Ventoy / multiboot USB detected). Your data WILL NOT persist across reboots." +fi + # --- /media/wrolpi/config + Postgres data layout ------------------------ # Works regardless of whether /media/wrolpi is a bind (Live), a regular # mount from /etc/fstab (Installed + external drive), or a plain @@ -253,7 +308,20 @@ systemctl start --no-block wrolpi-api.service wrolpi-app.service wrolpi-kiwix.se # If we did anything notable, leave a summary for the XFCE autostart to # show as a zenity dialog once the user lands on the desktop. if [ -n "$SUMMARY" ]; then - cat > "$SUMMARY_FILE" < "$SUMMARY_FILE" < "$SUMMARY_FILE" <