Skip to content
Wattcloud

Upgrade & rollback

wattcloud-update is installed alongside the relay and follows the same trust chain as install.sh: cosign verification against TRUSTED_SIGNER_IDENTITY, then atomic symlink swap, then health check, then auto-rollback on failure.

Routine upgrade

Section titled “Routine upgrade”
Terminal window
sudo wattcloud-update            # latest stable

Latest stable means the newest tag without a prerelease suffix (v1.0.0-rc.1 is skipped, v1.0.0 is not). The current symlink points at the new release once /health comes back green.

Pinning to a specific version

Section titled “Pinning to a specific version”
Terminal window
sudo wattcloud-update vX.Y.Z

Useful for staged rollouts across multiple hosts, or for deferring a release while a regression is investigated.

Rollback

Section titled “Rollback”
Terminal window
sudo wattcloud-update --rollback

--rollback swaps current back to the previously running release directory and restarts the unit. Past releases stay on disk for this exact reason, so the rollback is a symlink flip — no download, no verify step.

The number of releases retained is governed by WC_KEEP_RELEASES in /etc/wattcloud/wattcloud.env (default: 3). Older releases past that limit are pruned at the end of each successful update.

What an update actually does

Section titled “What an update actually does”
  1. flock the update lock so two concurrent invocations cannot race.
  2. Resolve the target tag via the GitHub API (stable only by default; skipped for prereleases unless the tag is explicit).
  3. Download the per-arch tarball, .sig, and .cert.
  4. cosign verify-blob against TRUSTED_SIGNER_IDENTITY. Failure aborts here — no extraction.
  5. Extract to /opt/wattcloud/releases/vX.Y.Z/.
  6. Diff .env.example against the live /etc/wattcloud/wattcloud.env. If the new release introduces required keys that are missing, abort with a human-readable list. No rollback is needed because the symlink was not touched.
  7. Reinstall the systemd unit only if the unit file content changed compared to the running unit. daemon-reload if so.
  8. Atomic symlink swap of /opt/wattcloud/current.
  9. systemctl reload-or-restart wattcloud, then poll /health for up to 30 seconds.
  10. Auto-revert on health failure: if /health does not come back, the symlink and unit are rolled back and the service is restarted on the previous release. Broken deploys never persist as current.
  11. Prune all but the last WC_KEEP_RELEASES release directories.

Verifying the update yourself

Section titled “Verifying the update yourself”

If you want to inspect a release before letting wattcloud-update install it:

Terminal window
TAG=vX.Y.Z
gh release download "$TAG" --repo wattzupbyte/wattcloud
make verify-tarball \
  TARBALL=wattcloud-${TAG}-x86_64-unknown-linux-gnu.tar.gz \
  SIG=…sig CERT=…cert

make verify-tarball runs the same cosign verify-blob invocation that install.sh uses, so a green local verify means the release will pass on the VPS too.

When the update aborts before flipping current

Section titled “When the update aborts before flipping current”

Common causes:

  • Cosign verification failure. Either the release was tampered with, or TRUSTED_SIGNER_IDENTITY does not match the source repo. journalctl -u wattcloud for the live release; the new release directory will have been removed.
  • Missing required env keys. The release diff prints the list of keys the new version expects but cannot find in /etc/wattcloud/wattcloud.env. Add the keys, then re-run wattcloud-update.
  • /health does not come back. Auto-rollback fires; the previous release is restored. journalctl -u wattcloud --since "5 min ago" is the first place to look for the cause. If the new release made it to the symlink-swap step at all, the new directory stays on disk under /opt/wattcloud/releases/ for forensics.

Adjacent docs

Section titled “Adjacent docs”