Skip to content

Upgrading Onionprobe

Onionprobe adopts the Semantic Versioning 2.0.0, which means that any major version might have breaking changes on previous installations.

The ChangeLog file contains the list of main changes from version to version, including breaking changes.

The following subsections documents other upgrade procedures, such as database updates.

Codebase upgrade

Standalone monitoring node

Upgrade procedures specific for the standalone monitoring node.

PostgreSQL database

Major upgrades

This procedure is based on the tianon/docker-postgres-upgrade approach1 and needs to be done whenever Onionprobe is upgraded to a new postgres image version:

Stop the monitoring node

Just run

./onionprobe-monitor down
Run the upgrade script

This handy script may do all the heavy lifting for you (requires sudo):

./scripts/upgrade-postgresql-database

By default it searches for the onionprobe_postgres service container, but you can pass the name of your custom container as the optional command line parameter:

./scripts/upgrade-postgresql-database <service-container-name>

The script also accepts optional arguments specifying the PostgreSQL versions:

./scripts/upgrade-postgresql-database <service-container-name> <old> <new>

Incremental upgrades

The database upgrades must be done incrementally, e.g. going from PostgreSQL 16 to 18 requires first upgrading from 16 to 17 and then from 17 to 18.

Backup

As a safeguard measure, the script does not remove it's working directory and also makes a backup of the old PostgreSQL data. You can manually remove those later after checking that the upgrade procedure works. Just follow the script output for instructions or check it's source code.

Start the monitoring node

Simply start the standalone monitoring node again after the upgrade procedure:

./onionprobe-monitor start

Collation upgrades

During system upgrades, it might also be needed to upgrade the collation version of the PostgreSQL databases.

Handled by the database upgrade script

Collation upgrades are already handled by the upgrade script mentioned above. The following instructions are needed only if the related warnings are still shown.

Run the following commands if you're getting warnings such as The collation in the database was created using version A.B.B, but the operating system provides version X.Y.Z:

$ ./onionprobe-monitor exec postgres psql -U grafana
grafana=# ALTER DATABASE grafana REFRESH COLLATION VERSION;
NOTICE:  changing version from 2.31 to 2.36
ALTER DATABASE
grafana=# ALTER DATABASE template1 REFRESH COLLATION VERSION;
NOTICE:  changing version from 2.31 to 2.36
ALTER DATABASE
grafana=# ALTER DATABASE postgres REFRESH COLLATION VERSION;
NOTICE:  changing version from 2.31 to 2.36
ALTER DATABASE
grafana=#

References:

Tor

Sometimes an image upgrade changes the debian-tor's UID and GID, which may require a manual ownership fix in the Docker volume data:

sudo chown -R 101:103 /var/lib/docker/volumes/onionprobe-instance_tor/_data

The same, for the case of Podman volume data:

sudo chown -R 101:103 $HOME/.local/share/containers/storage/volumes/onionprobe_tor/_data

  1. See tpo/onion-services/onionprobe#70 for more information. ↩