* 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>
3 KiB
Upgrading WROLPi
Table of Contents
- Upgrading Docker containers
- Upgrading Raspberry Pi or Debian Installation
- Upgrading a WROLPi Portable USB
Upgrading Docker containers
- Stop docker containers
docker-compose stop
- Pull the latest master
git pull origin master --ff
- Build all docker containers
docker-compose build --parallel
- Create the map volumes
docker volume create --name=openstreetmap-datadocker volume create --name=openstreetmap-rendered-tiles
- Turn on the database
docker-compose up -d db
- Upgrade the database
docker-compose run --rm api db upgrade
- 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.
- 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).
- Download the new
WROLPi-v*-amd64.isofrom wrolpi.org. - Plug the WROLPi USB into a Linux host and identify its device node (e.g.
/dev/sdb) withlsblk. - Run the upgrade:
sudo ./scripts/wrolpi-usb.sh upgrade WROLPi-v<version>-amd64.iso /dev/sdX
- 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:
- Back up everything on the drive to another disk.
- Flash the whole drive with the ISO (
dd/Etcher/Rufus — 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.