mirror of
https://github.com/lrnselfreliance/wrolpi.git
synced 2026-10-26 19:01:39 -04:00
All three build targets move from Debian 12/bookworm to Debian 13/trixie for fresh installs; existing Debian 12 systems remain supported in place. Docker: api/help on python:3.13-trixie, controller on 3.13-slim-trixie, app on node:20-trixie (matches trixie's nodejs 20), samba/zim on debian:13. Full backend suite passes on Python 3.13 in the api container. debian-live-config: --distribution trixie; postgres teardown for the SQLite cutover (pg_dropcluster hook block removed, wrolpi-bootstrap.sh no longer creates a cluster or calls the deleted initialize_api_db.sh — the API creates wrolpi.db itself on first start). README documents the SQLite layout and drops Etcher recommendations. pi-gen: upstream has no trixie branch — the arm64 branch now defaults to RELEASE=trixie; KEYBOARD_KEYMAP=en_US is rejected by trixie's console-setup (ckbcomp validates), use 'us'; stop stamping a Postgres .pgpass into /etc/skel. Package lists (both targets): postgresql-15/postgresql-doc/libpq-dev deleted; libtiff5-dev renamed to libtiff-dev; software-properties-common and cpufrequtils removed from trixie (Controller CPU throttle falls back to sysfs, dead cpufreq-set sudoers rule removed); locales and gnupg added (no longer arrive transitively under --apt-recommends false); sqlite3 CLI added for reset_tags.sh. help.sh: replace the Postgres service/port/socket/cluster/psql checks (all false FAILEDs after the SQLite cutover) with SQLite checks: wrolpi.db exists, PRAGMA quick_check, file_group table + row count, run as the wrolpi user so root never creates the -shm sidecar. Both build scripts take a WROLPI_BUILD_DIR override so development builds can run beside the release pipeline's build trees; the sudo re-exec passes it through explicitly (a plain sudo would drop it). test_common.py: the truncate tests hard-coded sys.getsizeof results from the 3.11 object layout (str/list shrank in 3.12); assert the contract (fits budget, prefix, monotonic in budget) so they pass on 3.11 and 3.13. Verified: trixie ISO (3.7G) and pi-gen desktop image (4.3G) both built from scratch and passed their sanity checks. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
136 lines
5.8 KiB
Markdown
136 lines
5.8 KiB
Markdown
# 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` installed. The resulting ISO is
|
|
written to this directory as `WROLPi-v${VERSION}-amd64.iso`.
|
|
|
|
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:
|
|
|
|
1. Back up everything on the drive to another disk.
|
|
2. Flash the whole drive with the ISO (Raspberry Pi Imager/Rufus/`dd` — this erases it).
|
|
3. Boot once so WROLPi creates its persistence partition and sets itself up.
|
|
4. 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.
|
|
|
|
## 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
|
|
|
|
- [x] **Phase 1 — merged live + chroot config**: Single `debian-live-config/`
|
|
produces a Debian Live ISO with the full WROLPi stack, XFCE auto-login
|
|
as `wrolpi`, persistence partition created on first boot.
|
|
- [x] **Phase 2 — Debian Installer**: Standard `debian-installer` bundled
|
|
via `lb 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's `live-installer` flow.
|
|
(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
|
|
|
|
- Debian Live Manual: https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html
|
|
- Persistence: https://live-team.pages.debian.net/live-manual/html/live-manual/customizing-run-time-behaviours.en.html
|