* A WROLPi serves its library over rsync, and makes a database snapshot on request The first part of replacing the sync: a secondary will copy its primary's whole media directory with rsync and replace its database with the primary's, instead of downloading the files of FileGroups over HTTP (which never copies an ignored directory, such as the map's). - An rsync daemon serves the media directory read-only on port 8873, on every WROLPi. It never serves the TLS keys, the cookies, or the database in use. On a Raspberry Pi and Debian it is the wrolpi-rsyncd unit; in Docker the Controller runs it in a helper container made from the api container (its image, user and volumes), so the media directory is still configured in one place. All three read controller/rsyncd.conf. - POST /api/sync/snapshot asks for a snapshot of the database, which the daemon serves from config/.sync. An unchanged database is not written again. - /api/sync/info also says the database's migration and whether the media directory is mounted. Nothing uses these yet; the existing sync is unchanged. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * The rsync daemon follows no links, and no snapshot is made in WROL Mode - A client that asked the daemon to follow symbolic links could read what a link in the library points at. A relative link to config/ssl was read this way although that directory is left out of the module. The daemon now refuses the three options that follow links; a link is sent as a link. - A database snapshot is a new file on the primary's drive, so WROL Mode refuses it, as it does a backup. A snapshot made earlier is still served. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> * No rsync helper from an image without rsync, and the helper follows the api container Review found: - A helper made from an api image built before rsync was added exits at once, and Docker restarted it forever while the Controller reported it created. The image is now looked at first; no helper is made from one without rsync, an older helper is left serving, and the reason is logged once. - The helper was only checked when the Controller started, so a recreated or rebuilt api container left it stale. It is now checked every minute. - A snapshot cut off by its process being killed stayed marked as running and held back every later request. - The snapshot's half-written temporary file was served by the daemon. - The comment on the daemon's refused options claimed more than they give: a link that is part of the requested path is still followed. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| config | ||
| files | ||
| build.sh | ||
| check-iso.sh | ||
| README.md | ||
Debian Live Config
Build a bootable amd64 ISO that boots into a full WROLPi system on any x86 PC. Users can run WROLPi directly off the USB (a persistence partition is created on the first boot so the database and media directory survive reboots) or install to disk via the Calamares launcher on the desktop.
The chroot-phase build is identical for both modes; the resulting squashfs is what runs in live mode AND what Calamares copies onto the target disk.
See https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html
Build
sudo ./build.sh # build from 'release' branch
sudo ./build.sh -b master # build from a specific branch
Requires Debian / Ubuntu with live-build, libarchive-tools (bsdtar),
genisoimage (isoinfo) and squashfs-tools installed. The resulting ISO is
written to this directory as
WROLPi-v${VERSION}-amd64.iso, and check-iso.sh then checks it for
problems that would only appear after the Debian installer runs.
Flash with Raspberry Pi Imager, Rufus, or:
sudo dd if=WROLPi-v${VERSION}-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync
Upgrading an existing WROLPi USB
A WROLPi USB carries two partitions: the ISO (boot) partition and a
persistence partition created on first boot that holds your library,
database, and configuration. To move to a newer ISO without losing the
persistence partition, use scripts/wrolpi-usb.sh from any Linux host:
sudo ./scripts/wrolpi-usb.sh upgrade WROLPi-v${VERSION}-amd64.iso /dev/sdX
It backs up the partition table, overwrites only the ISO partition, and re-adds the persistence partition entry at its original location. The ISO partition reserves 8 GiB of headroom so a larger future ISO still fits ahead of the persistence partition.
Converting an existing data drive (not supported)
There is no in-place conversion of a drive that already holds your data
into a WROLPi USB — flashing the ISO erases the whole drive, and there
is no safe, filesystem-agnostic way to graft WROLPi onto a full drive.
scripts/wrolpi-usb.sh install only prints this procedure:
- Back up everything on the drive to another disk.
- Flash the whole drive with the ISO (Raspberry Pi Imager/Rufus/
dd— this erases it). - Boot once so WROLPi creates its persistence partition and sets itself up.
- Copy your data into
/media/wrolpi/, then let WROLPi refresh/repair to index the restored files.
Afterwards, future ISO upgrades preserve your library via the
upgrade command above.
Users
wrolpiis a system account (no password, no login sudo) that owns/media/wrolpiand runs the WROLPi services, as on every other WROLPi.- The live session logs in automatically as
user(live-config), passwordlive. SSH accepts that password (sshd_config.d/50-wrolpi-password.confoverrides live-config, which turns password SSH off). - An installed system has the user the Debian installer asked for, with sudo, and no automatic login.
Layout on disk
The drive carries everything WROLPi needs. The SQLite database lives alongside the user's library so a drive moved between hosts keeps its full state:
/media/wrolpi/
videos/ ← user-facing media
archives/
zims/
map/
tags/
config/
wrolpi.yaml
controller.yaml
fstab.yaml
ssl/
wrolpi.db ← SQLite database (created by the
API on first start; -wal/-shm
sidecars appear while running)
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. The config
layout and SQLite database are created as usual, 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 Raspberry Pi Imager or dd.
Direct (Raspberry Pi Imager/dd) 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
- Phase 1 — merged live + chroot config: Single
debian-live-config/produces a Debian Live ISO with the full WROLPi stack, XFCE auto-login asuser, persistence partition created on first boot. - Phase 2 — Debian Installer: Standard
debian-installerbundled vialb config --debian-installer live --debian-installer-gui true. GRUB exposes "Live", "Install", and "Graphical Install" entries. Live boots into WROLPi; Install/Graphical Install copy the running squashfs onto the target disk via Debian'slive-installerflow. (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.) - Phase 3 — Ventoy/multiboot safety:
wrolpi-bootstrap.shdetects when it's been booted via a loop-mounted ISO (Ventoy and friends) and falls back to a tmpfs-backed/media/wrolpiinstead of writing a new partition onto the user's multiboot stick. - Release: CI on tag, hosting, wrolpi.org docs.