Skip to main content
An upgrade replaces one binary and keeps everything under ~/.stampede. Most releases need nothing else, but some move the store to a new schema at first start, and that step is one way: the older binary then refuses the store as newer than itself. The procedure below works for every release and makes the way back explicit.

Procedure

Run every step as the service user, with no request running. Read the release’s entry in the release notes first for its behaviour changes.
1

Download and verify

Download the new stampede-linux-x86_64 and SHA256SUMS into a fresh directory, and compare the sha256 with the value in the release notes:
Do not continue unless the check prints stampede-linux-x86_64: OK and the sha256 matches the release notes.
2

Stop the workers

Stopping first means no old worker picks up the new binary halfway, and no schedule fire or webhook delivery starts while you edit the configuration.
3

Keep the old binary and back up the home

The copy holds the store, its keys, the vault and the env file. Keep it private (directories 0700, files 0600) and delete it once the new version has run well. The backup is required before a release that moves the schema, and cheap insurance before any other.
4

Install the new binary

If the release adds a configuration key you want, add it now. An older binary refuses a config.toml that holds a key it does not know, so add new keys only after the new binary is installed.
5

Reinstall the units

service install rewrites the units for the new version and starts the workers. A plain restart keeps the old unit files. Every worker should show running.
6

Check the installation

No row may be FAIL. See Services and doctor for each row.
On a macOS install built from source, rerunning ./install.sh --name NAME with the newer tree replaces the binary and reruns service install. Stop the workers and back up the home first in the same way.

Rollback

When the release did not move the schema:
When the release moved the schema, the old binary cannot read the store, so put the backup back as well:
Everything done after the backup is lost. Before going back in either case, remove any configuration key the older release does not know (the table below names them), or the older binary refuses the file. If you are going back from 0.5.2 or later to 0.5.1 or earlier and a webhook worker was installed, run stampede service uninstall webhook with the newer binary still installed and check that the unit is gone. An older binary cannot run or remove a webhook unit.

Store schema and configuration changes

The migration runs on the first start of the new binary, whichever command starts first.

Behaviour changes per release

Runs in flight

A run recorded by an older binary may be refused automatic resume after the upgrade when the release changed what the run’s access means or what tools it has. It is refused rather than resumed under different rules. Finish or conclude long runs (stampede runs conclude RUN_ID) before upgrading if you need them to complete. Going back to an older binary has a similar limit: a run recorded by a newer version can carry state the older binary reads as corrupt. Finish or conclude those runs before downgrading.