Skip to content

Upgrading Onionspray

Upgrading Onionspray can be done in many ways, an in this guide we mention only a few.

Always backup before upgrading

In any case, always backup your setup before doing an upgrade.

Read the ChangeLog

Always check the ChangeLog before doing an upgrade, especially paying attention to any breaking change that may impact your setup. There you can find specific procedures to handle these breaking changes.

Simpler approach: start all over

If unsure, get a fresh copy of the Onionspray repository:

  • First, stop the services.
  • Then move the existing installation away to some other location (say from /srv/onionspray to /srv/onionspray.20240207).
  • Then clone the Onionspray repository into the desired local (say /srv/onionspray).
  • Proceed with the installation.
  • Import your existing .onion keys, HTTPS certificates and configuration files from the previous installation.
  • Reconfigure all your projects.
  • Start everything.

Usual approach: upgrade an existing installation

If you prefer, you can upgrade an existing installation in place after backing up and reading the ChangeLog.

Go to the Onionspray installation

First, go to the Onionspray folder:

cd /path/to/onionspray

Update the Onionspray repository copy

Then update the Git repository working copy, by either running git pull or

./onionspray update

You can also checkout Onionspray in a specific release/revision by using git directly.

Run the upgrade procedure

Then run Onionspray's built-in upgrade command, which might work for all the supported platforms:

./onionspray upgrade

This is useful if the new Onionspray version relies on updated upstream binaries: the script will only build things if new versions are detected. You can safely skip this if you're relying on upstream packages.

If Onionspray cannot find and appropriate build script, you may find it manually by looking in the opt/ folder. Please open a ticket or send a merge request if your system is currently unsupported.

The upgrade scripts can also be invoked directly.

Example using Debian trixie:

./opt/build-debian-trixie.sh

Then reconfigure each existing project:

./onionspray config myproject.conf

Restart all projects

Finally, restart all your projects:

./onionspray restart -a

If you're running softmaps, please also restart Onionbalance:

./onionspray ob-restart -a