Upgrading Waveshift

Roll an existing Waveshift deployment forward to a new release.

Page in progress

The v0.5 upgrade flow is being captured against the wsctl TUI. The previous v0.3 → v0.4 process — hand-editing systemd unit files inside the orchestrator EC2 instance — is no longer the supported path.

Until the new walkthrough lands, the safe play for v0.4 → v0.5 is a clean deploy:

1. Capture any state you want to preserve from the existing Console (user list, sites, licence JWT, etc.).
2. Tear the v0.4 deployment down with the v0.4 wavectl (wavectl deploy --destroy all).
3. Install the v0.5 wsctl binary and follow Deploy walkthrough.
4. Re-create users / sites / licence in the new Console.

For point upgrades within v0.5 (e.g. v0.5.0 → v0.5.1), the TUI's Upgrade menu has an Upgrade Services entry that is not yet enabled (it shows Coming soon).

Router firmware

After upgrading the orchestrator, also upgrade the firmware on your GL.iNet routers — see Upgrading router firmware.

Best practices

• Plan a maintenance window. The orchestrator restart is brief but the Console is unreachable while it happens.
• Tear down active Egress Servers first. Active builds aren't guaranteed to clean up cleanly across major-version upgrades.
• Watch the logs after restart. SSM into the orchestrator and tail journalctl -u waveshift -u frontend for a few minutes (the orchestrator and Console run as the waveshift.service and frontend.service systemd units).

See also

• wsctl — overview of the CLI.
• Common issues — symptoms with first-thing-to-check for each.