wrolpi/UPGRADE.md
lrnselfreliance bde1209c63
An upgrade refuses to roll back to an older commit of the current branch (#910)
* An upgrade refuses to roll back to an older commit of the current branch

upgrade.sh verifies the fetched commit's signature, but a signature proves a commit is
WROLPi's, not that it is the newest; an intercepted fetch could serve an old signed
release and the forced checkout would roll the device back to it.  refuse_rollback stops
when the target is an older commit of the branch the device is on (a detached HEAD from a
release image counts as that branch).  Branch switches, the same commit, and history the
device does not contain (Debian 12 devices on debian12-final) are allowed, and -d allows
a deliberate downgrade; it reaches the upgrade service through the env file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* An upgrade also refuses a signed commit with a lower version from other history

Ancestry alone only caught older commits in the device's own history; any other signed
commit, such as debian12-final or an old experimental branch, passed.  refuse_rollback
now also compares wrolpi/version.txt, which is inside the signed tree, and refuses a lower
or missing version.  A force-pushed branch at the same or a higher version still upgrades.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Tests pin the two parts of refuse_rollback that only one rule catches

An earlier commit of the same version is refused only by the ancestry check, and
0.30.10-beta after 0.30.3-beta only orders correctly with sort -V; the fixture's
single-digit versions passed with either part removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 09:33:25 -06:00

3 KiB

Upgrading WROLPi

Table of Contents

Upgrading Docker containers

  1. Stop docker containers
    • docker-compose stop
  2. Pull the latest master
    • git pull origin master --ff
  3. Build all docker containers
    • docker-compose build --parallel
  4. Create the map volumes
    • docker volume create --name=openstreetmap-data
    • docker volume create --name=openstreetmap-rendered-tiles
  5. Turn on the database
    • docker-compose up -d db
  6. Upgrade the database
    • docker-compose run --rm api db upgrade
  7. Start all docker containers
    • docker-compose up -d

Upgrading Raspberry Pi or Debian Installation

A Debian 12 (bookworm) WROLPi stays on the final version for Debian 12; reinstall on Debian 13 to get newer versions.

  1. Run the upgrade script
    • sudo /bin/bash /opt/wrolpi/upgrade.sh
    • (If the upgrade script does not exist, run the installation script: sudo /bin/bash /opt/wrolpi/install.sh)
    • The upgrade refuses to move back to an older commit of the branch you are on. To downgrade on purpose, run sudo /bin/bash /opt/wrolpi/upgrade.sh -d.

Upgrading a WROLPi Portable USB

A WROLPi Portable USB carries two partitions: the ISO (boot) partition and a persistence partition — created on the first boot — that holds your library, database, and configuration. To move to a newer ISO without losing the persistence partition, use the scripts/wrolpi-usb.sh tool from any Linux host (your own computer, or the WROLPi USB itself booted on another machine).

  1. Download the new WROLPi-v*-amd64.iso from wrolpi.org.
  2. Plug the WROLPi USB into a Linux host and identify its device node (e.g. /dev/sdb) with lsblk.
  3. Run the upgrade:
    • sudo ./scripts/wrolpi-usb.sh upgrade WROLPi-v<version>-amd64.iso /dev/sdX
  4. Eject the USB and boot it to verify.

The tool backs up the current partition table to /tmp/ first, 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 is not supported

There is no in-place conversion of a drive that already holds your data into a WROLPi Portable USB — flashing the ISO erases the whole drive. To turn a drive you already use into a WROLPi USB without losing your files:

  1. Back up everything on the drive to another disk.
  2. Flash the whole drive with the ISO (dd/Etcher/Rufus — 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.